Блог GunSmoker-а

Разработка системы плагинов, часть 3: активные плагины

2012-01-11T05:04:00.002+04:00

В прошлой части мы реализовали пассивные плагины: они просто предоставляли функции, а ядро их вызывало по мере надобности. Сам же плагин был полностью пассивен, он не инициировал никаких действий в ядре. В этой части мы рассмотрим более сложные методы общения между ядром и плагинами.

Что хотим

Здесь и далее я лишь кратко буду озвучивать идею метода - для экономии места и времени, но при этом я предполагаю, что в вашей реальной программе вы будете прорабатывать всё это полностью - как мы делали это в прошлый раз, включая предварительное проектирование, формальное определение контракта и документацию.

В качестве примера к этой статье я предлагаю разрешить плагинам встраиваться в меню нашей программы. Тогда, если пользователь щёлкнет по пункту меню плагина, плагин должен отреагировать и выполнить какую-то работу. Понятно, что для этого плагину придётся "дёргать" ядро, уже по инициативе самого плагина, а не ядра.

Пока у нас нет ничего, что плагин мог бы "дёргать", поэтому сейчас никакой полезной работы он (плагин) выполнить не сможет. По этой причине я предлагаю также ввести в программу возможность манипулирования текстовым редактором. Тогда мы могли бы написать плагин, который, скажем, добавлял бы в меню такие пункты: "Преобразовать разделители строк в <br/>", "Обрамить жирный текст в <b></b>" или "Изменить регистр всех символов на ВЕРХНИЙ". В общем, много чего придумать можно.

От меню требуется дать возможность плагинам добавлять туда свои пункты меню, а также модифицировать их (например, отключать или менять заголовок) и реагировать на события (например, щелчки мышью). В принципе, это можно сделать, как и ранее - пусть плагин реализует гипотетический интерфейс IPluginMenuItem. Тогда ядро может это увидеть и создать для плагина пункт меню при его загрузке. Это будет повторение уже известного "пассивного" подхода. Но если в прошлом примере с экспортом/импортом этот подход работал отлично, то здесь уже он не достаточно гибок - ведь плагину может потребоваться более одного пункта меню.

Поэтому я предлагаю использовать другой подход, с обратным вызовом (callback). Вспомните, что при загрузке плагина ядро передаёт ему "себя" - ICore. Плагин волен делать с этой ссылкой всё, что ему угодно, в любой момент времени. Понятно, что сейчас там есть всего один метод - получение версии ядра, но никто же не запрещает нам ввести туда метод вида "а ну-ка, создай для меня новый пункт меню!". Тогда плагин в любой момент времени (но, конечно же, чаще всего - при загрузке) может вызвать этот метод ядра (и даже несколько раз подряд) и создать себе сколько угодно пунктов меню. Это и есть активный подход: уже не ядро командует плагином, а сам плагин дёргает ядро.

С редактором текста программы имеет место быть полностью аналогичная ситуация. Ядро предоставляет плагинами интерфейс для манипуляции редактором текста, так что плагины могут выполнять произвольные операции с текстом.

Управление меню

Итак, нам понадобится, во-первых, интерфейс для создания и удаления пунктов меню, методы которого будет вызывать плагин. Выглядит он очень просто:

type
  IMenuManager = interface
  ['{216082F8-8FE8-4B51-83E5-C8324452AD18}']
    function CreateMenuItem: IMenuItem; safecall;
    procedure DeleteMenuItem(var AItem: IMenuItem); safecall;
  end;

Я поясню выбор var для параметра AItem в методе DeleteMenuItem чуть позднее.

Далее, нам нужен интерфейс для самого пункта меню. Предлагаю такой вариант:

type
  IMenuItem = interface
  ['{B1A0A830-532B-4573-AE19-33EAA4D76096}']
  // private
    function GetCaption: WideString; safecall;
    function GetChecked: BOOL; safecall;
    function GetEnabled: BOOL; safecall;
    function GetHint: WideString; safecall;
    procedure SetCaption(const AValue: WideString); safecall;
    procedure SetChecked(const AValue: BOOL); safecall;
    procedure SetEnabled(const AValue: BOOL); safecall;
    procedure SetHint(const AValue: WideString); safecall;
  // public
    property Caption: WideString read GetCaption write SetCaption;
    property Checked: BOOL read GetChecked write SetChecked;
    property Enabled: BOOL read GetEnabled write SetEnabled;
    property Hint: WideString read GetHint write SetHint;
    procedure RegisterExecuteHandler(const AEventHandler: INotifyEvent); safecall;
  end;

Этот интерфейс позволит нам изменять основные свойства пункта меню. Вы можете добавить что-то ещё или что-то убрать - это ваш выбор. Метод RegisterExecuteHandler служит как замена события OnClick. Я подробнее продемонстрирую его работу позже. INotifyEvent же объявлен так:

type
  INotifyEvent = interface
  ['{80B8A93C-B69B-49BA-BD7C-749629C9D97B}']
    procedure Execute(Sender: IInterface); safecall;
  end;

Это что касается заголовочников. Теперь по реализации.

Давайте начнём с конца. Кто должен реализовывать IMenuItem? Ну, это точно не менеджер плагинов - ведь он один, а пунктов меню много. И это точно не обёртка плагина в менеджере плагинов - их хоть и много, но у нас есть всего одна обёртка для плагина, в то время как один плагин может создать несколько пунктов меню.

Наиболее разумно будет выбрать сам элемент меню для реализации IMenuItem. Делается это очень просто:

type
  TPluginMenuItem = class(TMenuItem, IUnknown, IMenuItem)
  private
    FClickHandler: INotifyEvent;
  protected
    // IMenuItem
    function GetCaption: WideString; safecall;
    function GetChecked: BOOL; safecall;
    function GetEnabled: BOOL; safecall;
    function GetHint: WideString; safecall;
    procedure SetCaption(const AValue: WideString); safecall;
    procedure SetChecked(const AValue: BOOL); safecall;
    procedure SetEnabled(const AValue: BOOL); safecall;
    procedure SetHint(const AValue: WideString); safecall;
    procedure RegisterExecuteHandler(const AEventHandler: INotifyEvent); safecall;
  public
    procedure Click; override;
  end;

{ TPluginMenuItem }

procedure TPluginMenuItem.Click;
begin
  inherited; // вызываем стандартную обработку

  // Вызываем плагин
  if Enabled and Assigned(FClickHandler) then
    FClickHandler.Execute(Self);
end;

function TPluginMenuItem.GetCaption: WideString;
begin
  Result := Caption;
end;

function TPluginMenuItem.GetChecked: BOOL;
begin
  Result := Checked;
end;

function TPluginMenuItem.GetEnabled: BOOL;
begin
  Result := Enabled;
end;

function TPluginMenuItem.GetHint: WideString;
begin
  Result := Hint;
end;

procedure TPluginMenuItem.SetCaption(const AValue: WideString);
begin
  Caption := AValue;
end;

procedure TPluginMenuItem.SetChecked(const AValue: BOOL);
begin
  Checked := AValue;
end;

procedure TPluginMenuItem.SetEnabled(const AValue: BOOL);
begin
  Enabled := AValue;
end;

procedure TPluginMenuItem.SetHint(const AValue: WideString);
begin
  Hint := AValue;
end;

procedure TPluginMenuItem.RegisterExecuteHandler(const AEventHandler: INotifyEvent);
begin
  FClickHandler := AEventHandler;
end;

Как видите, этот код тривиален - простой переходник TMenuItem <-> IMenuItem.

Далее, эти самые элементы меню кто-то должен создавать. Понятно, что делаться это будет по указке плагина, но внутри программы эти пункты меню должен создавать код программы. Кто это будет? В принципе, вот тут уже этим мог бы заниматься менеджер программы. Но тут есть два "но":

Мы делаем код менеджер плагинов зависимым от нашей программы. Я уже сделал такую "плохую вещь" в прошлый раз - введением свойства FilterIndex. Тогда я пояснил, что это - "плохо", но выбрал этот путь как самый простой. Здесь ситуация аналогична - можно сделать быстро и грязно, а можно... сейчас посмотрим как.
Недостаток два - это то, что менеджер плагинов будет заниматься не своими обязанностями. Какова задача менеджера плагинов? Служить менеджером плагинов, конечно же! Управление меню - это не обслуживание плагинов. Это - обслуживание интерфейса пользователя. А какой класс занимается обслуживанием UI? Конечно же, форма!

Итак, как вы уже поняли - подходящим кандидатом для реализации IMenuManager будет форма (в моём примере - TMainForm):

type
  TMainForm = class(TForm, IMenuManager)
  ...
  protected
    // IMenuManager
    function CreateMenuItem: IMenuItem; safecall;
    procedure DeleteMenuItem(var AItem: IMenuItem); safecall;
  end;

...

implementation

...

function TMainForm.CreateMenuItem: IMenuItem;
var
  MI: TPluginMenuItem;
begin
  MI := TPluginMenuItem.Create(miPlugins);
  Result := MI;
  miPlugins.Add(MI);

  miPlugins.Visible := True;
end;

procedure TMainForm.DeleteMenuItem(var AItem: IMenuItem);

  function GetComponent(var AItem: IMenuItem): TPluginMenuItem;
  var
    Internal: IInterfaceComponentReference;
  begin
    if not Supports(AItem, IInterfaceComponentReference, Internal) then
      Assert(False);
    Result := Internal.GetComponent as TPluginMenuItem;
    Internal := nil;
    AItem := nil;
  end;

begin
  GetComponent(AItem).Free;

  miPlugins.Visible := (miPlugins.Count > 0);
end;

...

end.

Вот тут начинается самое интересное. Видите ли, элемент меню - это компонент (наследник TComponent). Это означает, что он удаляется явно - вызовом деструктора, а вовсе не тогда, когда исчезнет последняя ссылка на него. С другой стороны, использование интерфейсов диктует другую идеологию. Это классическая проблема стыкования двух различных механизмов управления временем жизни: ручного и автоматического на базе подсчёта ссылок. Для этой проблемы есть несколько решений.

Прежде всего замечу, что удалять пункт меню по удалению последней ссылки на него будет не самой удачной идеей. Почему? Потому что чаще всего плагину нужно просто создать пункт меню, настроить его и... всё. Дальше пункт меню должен жить, но плагину нет нужды хранить на него ссылку, потому что ему не нужно ничего менять. Поэтому хорошо бы дать ему возможность "забыть" ссылку без удаления пункта меню.

Метод номер два заключается в введении метода явного удаления - аналога деструктора в интерфейс. Скажем, Delete. Когда этот метод вызывается - пункт меню надо удалить (даже если ссылки на интерфейс ещё не обнулены). После вызова метода пункт меню будет удалён, а интерфейс останется жить, но любое обращение к его методам вызовет ошибку "нет пункта меню". Так что единственное, что с этим интерфейсом можно будет сделать - освободить (уменьшить число ссылок). Этот способ довольно привлекателен, но имеет и минусы: вам нужно два объекта. Один - это пункт меню. Этот объект будет удаляться при вызове метода Delete. Второй объект - это реализатор интерфейса. Он удаляется при уменьшении счётчика ссылок до нуля. Это не может быть тот же самый объект, потому что первый объект нужно удалять по вызову Delete - когда счётчик ссылок ещё не равен нулю.

Я предлагаю компромиссный способ 3, при котором нам понадобится один объект (TPluginMenuItem), но при этом для плагина остаётся возможность "забыть" ссылку без удаления пункта меню. Способ заключается в том, что мы вводим функцию удаления пункта меню в менеджер меню. Функция принимает ссылку на пункт меню, который нужно удалить. При этом ставится условие, что это должна быть последняя ссылка на пункт меню. Тогда: если плагину не нужен пункт меню после его создания - он просто забудет ссылку на него и ничего не произойдёт, пункт меню удалён не будет. Если же плагину в итоге нужно будет удалить пункт меню, он сохраняет ссылку на него, а для удаления он сначала удаляет все свои дополнительные ссылки на пункт меню (если он их создавал), после чего передаёт оставшуюся (последнюю) ссылку в функцию удаления. Функция удаления удаляет пункт меню и ссылку одновременно - таким образом, два механизма управления временем жизни остаются согласованными.

Конечно же, вы можете использовать другой метод. Я подчеркну, что я описываю какой-то способ реализации плагинов. Он не является единственным правильным. Тут можно делать как угодно. Вы проектируете API. Это означает, что будет так, как скажете вы. Это означает, что тут всё зависит от ваших потребностей и фантазии.

Ещё замечу, что в указанной модели подразумевается, что пункты меню, созданные плагином, будут отслеживаться и удаляться при выгрузке плагина. Поскольку у меня не сделано отслеживание пунктов меню, то функциональность "забыть ссылку без удаления" сейчас работать не будет. Вернее, работать-то она будет, но пункты плагина останутся висеть в меню вечно. Я оставлю доработку на следующий раз, где поговорю о вопросах общения плагинов между собой (это тесно связанный с указанной темой вопрос), а пока пусть плагины за собой чистят явно.

В рамках же указанного подхода остаётся лишь сделать замечание по реализации этой самой функции удаления пункта меню (DeleteMenuItem). Во-первых, вы уже поняли, почему у её параметра стоит модификатор var, а не что-то другое: чтобы можно было обнулить ссылку. Далее, поскольку мы удаляем объект TMenuItem (с ручным управлением временем жизни), то мы не можем просто обнулить ссылку - это не удалит объект. Нам нужно получить сам объект и вызвать его деструктор (кстати, ссылку надо обнулить до вызова деструктора). Окей, как можно получить ссылку на реализующий объект по интерфейсу? Есть аж четыре способа:

Перебор: перебрать все пункты меню и найти с подходящим интерфейсом.
Грязный хак.
Дополнительный служебный интерфейс, возвращающий Self.
Новые возможности интерфейсов в Delphi 2010 и выше.

Перебор - это долго, хак - это грязно, Delphi 2010 используют не все (к сожалению), поэтому выход - номер 3.

Поскольку я делал этот пример в Delphi XE, то у меня уже есть весь готовый код для этого. Если же вы используете более старую версию Delphi, то вам может понадобится изменить код так:

type
  IInterfaceComponentReference = interface
  ['{41D23E9C-0974-4ED4-BBE8-4375D65E1129}']
    function GetComponent: TObject;
  end;

...

type
  TPluginMenuItem = class(TMenuItem, IUnknown, IInterfaceObjectReference, IMenuItem)
  ...
  protected
    function GetComponent: TObject;
    ... 
  public
    ...
  end;

function TPluginMenuItem.GetComponent: TObject;
begin
  Result := Self;
end;

Код достаточно очевиден: мы ввели скрытый интерфейс для служебных целей. Интерфейс просто выставляет нам Self - что и будет объектом, который реализует интерфейс.

Осталось пояснить, почему я выделил подпрограмму GetComponent. Вы могли бы подумать, что я сделал это с точки зрения хорошего стиля, но это лишь часть правды. Дело тут в том, что мы должны освободить все ссылки на объект до его удаления. С AItem вопросов нет - это последняя ссылка, нам это должен гарантировать плагин. Но мы работаем с интерфейсами в своём коде. И проблема тут в том, что при этом компилятор может создавать скрытые интерфейсные ссылки, которые освобождаются в момент выхода их из области видимости - т.е. в строчке "end;" этой процедуры. А это - после вызова деструктора. К этой проблеме есть два решения. Первое: просто просмотреть код и убедиться, что скрытых ссылок нет. Дело это не всегда тривиальное и тут можно легко ошибиться - особенно при дальнейшей модификации и поддержке кода. Поэтому я предлагаю более простое решение - вынести весь код по работе с интерфейсами в отдельную подпрограмму, вызываемую до удаления пункта меню. Таким образом, если скрытые ссылки и будут созданы - они будут удалены в момент завершения этой вложенной подпрограммы, что случится до удаления пункта меню.

Так, что касается согласования двух моделей управления временем жизни - с этим всё. Замечу только, что у нас есть ещё форма, которая тоже, вроде бы, управляется вручную, но для неё указанная проблема не возникает - это потому, что форма живёт дольше, чем плагины (я добавил выгрузку плагинов в OnDestroy формы - нет смысла делать иначе, поскольку плагины в нашей программе работают только с UI). Это означает, что время жизни формы больше времени жизни плагинов, они не пересекаются. Т.е. последняя ссылка на форму (менеджер меню) будет удалена до удаления формы - таким образом, никаких проблем, требующих решения, не возникает.

Итак, теперь у нас есть готовый менеджер меню, который позволяет плагинам создавать пункты меню, менять их и реагировать на щелчки в них. Остаётся небольшой вопрос: как плагин получит доступ к менеджеру меню? Действительно: плагин инициализируется передачей ему менеджера плагинов, но никакой ссылки на менеджер меню там нет. Вот эту проблему сейчас нам и нужно решить. Делается это так (файл PluginManager.pas):

type
  IPluginManager = interface
    ...
    procedure RegisterServiceProvider(const AProvider: IUnknown);
  end;

...

implementation

...

type
  TPluginManager = class(TInterfacedObject, IUnknown, IPluginManager, ICore)
  private
    ...
    FProviders: TInterfaceList;
  protected
    ...
    procedure RegisterServiceProvider(const AProvider: IUnknown);
    function QueryInterface(const IID: TGUID; out Obj): HResult; stdcall;
  end;

...

constructor TPluginManager.Create;
begin
  ...
  FProviders := TInterfaceList.Create;
  ...
end;

destructor TPluginManager.Destroy;
begin
  FreeAndNil(FProviders);
  ...
end;

procedure TPluginManager.UnloadAll;
begin
  Finalize(FItems);
  FProviders.Clear;
end;

procedure TPluginManager.RegisterServiceProvider(const AProvider: IUnknown);
begin
  FProviders.Add(AProvider);
end;

function TPluginManager.QueryInterface(const IID: TGUID; out Obj): HResult;
var
  X: Integer;
begin
  Result := inherited QueryInterface(IID, Obj);
  if Failed(Result) then
  begin
    for X := 0 to FProviders.Count - 1 do
    begin
      Result := FProviders[X].QueryInterface(IID, Obj);
      if Succeeded(Result) then
        Break;
    end;
  end;
end;

...

end.

И файл remain.pas:

procedure TMainForm.FormCreate(Sender: TObject);
begin
  SetErrorMode(SetErrorMode(0) or SEM_NOOPENFILEERRORBOX or SEM_FAILCRITICALERRORS);
  Plugins.SetVersion(1);
  Plugins.RegisterServiceProvider(Self); // <- добавлено
  Plugins.LoadPlugins(ExtractFilePath(ParamStr(0)) + 'Plugins', SPluginExt);
  BuildFilterList;

  ...
end;

Если вы посмотрите внимательнее, то увидите, что весь трюк здесь заключается в подмене метода QueryInterface: мы модифицируем его так, чтобы он возвращал не только интерфейсы самого объекта, но и ещё "чьи-то". Если вы помните, то эту технику мы уже использовали: в прошлый раз - подмена QueryInterface в классе TPlugin. Только в последнем примере мы ищем дополнительные интерфейсы не у кого-то конкретного, а в целом списке, позволяя при этом стороннему коду (стороннему - по отношению к менеджеру плагинов) производить регистрацию себя в качестве "поставщика интерфейсов". В итоге у нас получается так, что плагин может запрашивать у менеджера плагинов (ядра) что угодно, но сам менеджер плагинов понятия не имеет, что же спрашивает у него плагин - зато про это имеет понятие программа, которая и регистрирует в менеджере плагинов интерфейсы для раздачи их плагинам.

С основной программой мы на этом закончили. Давайте кратко просуммируем сделанное: мы реализовали менеджер меню, научились согласовывать две модели управления временем жизни и реализовали "правильный" подход к менеджеру плагинов (регистрация функциональности ядра).

Теперь давайте посмотрим на реализацию плагина. Поскольку редактор у нас пока не готов для общения с плагинами, то я пока что покажу простой пример плагина, который работает только с меню: пусть он создаст несколько пунктов меню и покажет, как он умеет с ними обращаться:

library SimpleMenu;

uses
  Windows,
  SysUtils,
  Classes,
  ActiveX,
  AxCtrls,
  PluginAPI in 'PluginAPI\Headers\PluginAPI.pas';

{$R *.res}
{$E .rep}

type
  TPluginMenuItem = class(TObject, IUnknown, INotifyEvent)
  private
    FManager: IMenuManager;
    FItem: IMenuItem;
    FClick: TNotifyEvent;
  protected
    // IUnknown
    function QueryInterface(const IID: TGUID; out Obj): HResult; virtual; stdcall;
    function _AddRef: Integer; stdcall;
    function _Release: Integer; stdcall;
    // INotifyEvent
    procedure Execute(Sender: IInterface); safecall;
  public
    constructor Create(const ACore: ICore);
    destructor Destroy; override;
    property Item: IMenuItem read FItem;

    procedure Click; virtual;
    property OnClick: TNotifyEvent read FClick write FClick;
  end;

  TPlugin = class(TInterfacedObject, IUnknown)
  private
    FCore: ICore;
    FMenuItem1: TPluginMenuItem;
    FMenuItem2: TPluginMenuItem;
    FMenuItem3: TPluginMenuItem;
    procedure MenuItem1Click(Sender: TObject);
    procedure MenuItem2Click(Sender: TObject);
    procedure MenuItem3Click(Sender: TObject);
  public
    constructor Create(const ACore: ICore);
    destructor Destroy; override;
  end;

{ TPlugin }

constructor TPlugin.Create(const ACore: ICore);
begin
  inherited Create;
  FCore := ACore;
  Assert(FCore.Version >= 1);

  FMenuItem1 := TPluginMenuItem.Create(FCore);
  FMenuItem2 := TPluginMenuItem.Create(FCore);
  FMenuItem3 := TPluginMenuItem.Create(FCore);

  FMenuItem1.Item.Caption := 'SimpleMenu: Отмечается галочкой';
  FMenuItem1.Item.Hint := 'Элемент №1 от плагина SimpleMenu';
  FMenuItem1.Item.Checked := True;
  FMenuItem1.OnClick := MenuItem1Click;

  FMenuItem2.Item.Caption := 'SimpleMenu: Показ сообщения';
  FMenuItem2.Item.Hint := 'Элемент №2 от плагина SimpleMenu';
  FMenuItem2.OnClick := MenuItem2Click;

  FMenuItem3.Item.Caption := 'SimpleMenu: Убрать все мои пункты меню';
  FMenuItem3.Item.Hint := 'Элемент №3 от плагина SimpleMenu';
  FMenuItem3.OnClick := MenuItem3Click;
end;

destructor TPlugin.Destroy;
begin
  FreeAndNil(FMenuItem3);
  FreeAndNil(FMenuItem2);
  FreeAndNil(FMenuItem1);
  inherited;
end;

procedure TPlugin.MenuItem1Click(Sender: TObject);
begin
  FMenuItem1.Item.Checked := not FMenuItem1.Item.Checked;
end;

procedure TPlugin.MenuItem2Click(Sender: TObject);
begin
  MessageBox(0, 'Привет от плагина SimpleMenu!', 'SimpleMenu', MB_OK or MB_ICONINFORMATION);
end;

procedure TPlugin.MenuItem3Click(Sender: TObject);
begin
  FreeAndNil(FMenuItem1);
  FreeAndNil(FMenuItem2);
  FMenuItem3.Item.Enabled := False;
end;

{ TPluginMenuItem }

constructor TPluginMenuItem.Create(const ACore: ICore);
begin
  inherited Create;
  if not Supports(ACore, IMenuManager, FManager) then
    Assert(False);

  FItem := FManager.CreateMenuItem;

  FItem.Caption := 'PluginMenuItem';
  FItem.Hint := '';
  FItem.Enabled := True;
  FItem.Checked := False;
  FItem.RegisterExecuteHandler(Self);
end;

destructor TPluginMenuItem.Destroy;
begin
  FManager.DeleteMenuItem(FItem);
  FManager := nil;
  inherited;
end;

procedure TPluginMenuItem.Execute(Sender: IInterface);
begin
  Click;
end;

procedure TPluginMenuItem.Click;
begin
  if FItem.Enabled then
  begin
    if Assigned(FClick) then
      FClick(Self);
  end;
end;

function TPluginMenuItem.QueryInterface(const IID: TGUID; out Obj): HResult;
begin
  if GetInterface(IID, Obj) then
    Result := S_OK
  else
    Result := E_NOINTERFACE;
end;

function TPluginMenuItem._AddRef: Integer;
begin
  Result := -1;   // -1 indicates no reference counting is taking place
end;

function TPluginMenuItem._Release: Integer;
begin
  Result := -1;   // -1 indicates no reference counting is taking place
end;

// _________________________________________________________________

function Init(const ACore: ICore): IUnknown; safecall;
begin
  Result := TPlugin.Create(ACore);
end;

procedure Done; safecall;
begin

end;

exports
  Init name SPluginInitFuncName,
  Done name SPluginDoneFuncName;

end.

Давайте начнём разбор кода. Во-первых, мы ввели вспомогательный класс TPluginMenuItem. Зачем он нужен? Дело в том, что мы хотим создать 3 пункта меню. При этом нам, конечно же, хотелось бы реагировать на щелчки по всем этим пунктам меню - т.е. нам нужно три обработчика событий OnClick. За это событие у нас отвечает интерфейс INotifyEvent с (единственным) методом Execute. С другой стороны, TPlugin - он у нас один, и он не может "реализовывать трижды" один и тот же интерфейс. Поэтому нам надо три объекта. Три TPlugin мы сделать не можем (плагин - он же один), поэтому мы и ввели TPluginMenuItem - это позволяет нам иметь несколько объектов, по одному на каждый пункт меню. Вспомогательный объект берёт на себя реализацию интерфейса, выставляя нам наружу удобный OnClick - прямо как в Delphi. Ну и, конечно же, объект предоставляет методы по управлению пунктом меню. Замечу, что тут я поленился и сделал просто property Item: IMenuItem вместо копирования функциональности - что сэкономило мне код, но привело к не слишком удобному обращению вида FMenuItem2.Item.Caption. И снова я повторюсь, что вы можете делать как угодно - на свой вкус.

Когда у нас есть вспомогательный объект (код которого тривиален), мы уже легко можем создавать пункты меню - работа с ними происходит в точности так же, как вы бы работали с пунктами меню в приложении Delphi без плагинов. Вы создали пункт меню, настроили его и назначили обработчик.

Что ещё хотелось бы тут отметить: возьмите на заметку то, в каком состоянии создаётся пункт меню. Например, такой вопрос: какой заголовок имеет пункт меню после вызова CreateMenuItem? Это - вопрос для фиксации в документации (это я вроде как напоминаю). Вы должны явно это указать. Конечно, вы можете сказать: "состояние пункта меню после создания не определено, вы должны явно инициализировать все его свойства" - что снимет с вас (как разработчика программы) всякую ответственность, но также приведёт к огромному дублированию кода - ведь тогда каждому плагину при создании каждого пункта меню придётся делать, к примеру, Enabled := True (ведь вы же чёрным по белому сказали "после создания - может быть любым"). Поэтому лучше бы, конечно, всё же явно установить состояние и придерживаться его в дальнейшем.

Второй момент - в этом примере я оставил предыдущие наработки. В частности, в программе есть плагины экспорта и импорта, и я приложил старые плагины для работы с RTF. Это показывает широкие возможности системы плагинов - работу с разнотипными плагинами. Кстати, обратите внимание, что у нас, по сути, вообще нет такого понятия "тип плагина". У нас всё упирается в то, какие интерфейсы поддерживает плагин. К примеру, один и тот же плагин теоретически может быть и плагином импорта и плагином экспорта (если только вы явно не запретите такую комбинацию в коде или в документации, как я указывал это в прошлый раз) и при этом же создавать пункты меню (например, для вызова диалога настроек импорта).

Скачать пример.

Управление редактором

Когда мы реализовали меню и подробно обсудили все моменты, у вас не должно возникнуть никаких сложностей с редактором меню. Как позволить плагинам работать с редактором? Реализовать интерфейс, конечно же! Кто должен реализовывать интерфейс? Ну, либо форма, либо сам редактор. А как плагины увидят этот интерфейс? А мы его зарегистрируем в менеджере плагинов.

Как видите, всё практически дословно повторяет предыдущий пример. Поэтому я кратко покажу код без объяснений. Полный исходный код можно скачать по ссылке в конце статьи.

Как будет выглядеть интерфейс? Например, так:

type
  TEditorSearchTypes = DWORD;

const
  esfWholeWord = 0;
  esfMatchCase = 1;

type
  IEditor = interface
  ['{F82E46C3-A744-4137-B9A0-242E50CC0041}']
  // private
    function GetText: WideString; safecall;
    procedure SetText(const AValue: WideString); safecall;
    function GetSelText: WideString; safecall;
    procedure SetSelText(const AValue: WideString); safecall;
    function GetSelStart: Integer; safecall;
    procedure SetSelStart(const AValue: Integer); safecall;
    function GetSelLength: Integer; safecall;
    procedure SetSelLength(const AValue: Integer); safecall;
    function GetModified: BOOL; safecall;
    function GetCanUndo: BOOL; safecall;
    function GetCaretPos: TPoint; safecall;
    procedure SetCaretPos(const AValue: TPoint); safecall;

  // public
    property Text: WideString read GetText write SetText;
    property SelText: WideString read GetSelText write SetSelText;
    property SelStart: Integer read GetSelStart write SetSelStart;
    property SelLength: Integer read GetSelLength write SetSelLength;
    procedure SelectAll; safecall;
    property Modified: BOOL read GetModified;
    property CanUndo: BOOL read GetCanUndo;
    procedure Undo; safecall;
    procedure ClearUndo; safecall;
    procedure Clear; safecall;
    procedure ClearSelection; safecall;
    procedure CopyToClipboard; safecall;
    procedure CutToClipboard; safecall;
    procedure PasteFromClipboard; safecall;
    property CaretPos: TPoint read GetCaretPos write SetCaretPos;
    function FindText(const SearchStr: WideString; const StartPos, Length: Integer; Options: TEditorSearchTypes): Integer; safecall;
  end;

(обсуждение TEditorSearchTypes мне хотелось бы оставить на другой раз)

Как будет выглядеть реализация? Например, так:

type
  TMainForm = class(TForm, IEditor, IMenuManager)
  ...
  protected
    ...
    // IEditor
    function GetText: WideString; safecall;
    procedure SetText(const AValue: WideString); safecall;
    function GetSelText: WideString; safecall;
    procedure SetSelText(const AValue: WideString); safecall;
    function GetSelStart: Integer; safecall;
    procedure SetSelStart(const AValue: Integer); safecall;
    function GetSelLength: Integer; safecall;
    procedure SetSelLength(const AValue: Integer); safecall;
    function GetModified: BOOL; safecall;
    function GetCanUndo: BOOL; safecall;
    function GetCaretPos: TPoint; safecall;
    procedure SetCaretPos(const AValue: TPoint); safecall;
    procedure SelectAll; safecall;
    procedure Undo; safecall;
    procedure ClearUndo; safecall;
    procedure Clear; safecall;
    procedure ClearSelection; safecall;
    procedure CopyToClipboard; safecall;
    procedure CutToClipboard; safecall;
    procedure PasteFromClipboard; safecall;
    function FindText(const SearchStr: WideString; const StartPos, Length: Integer; Options: TEditorSearchTypes): Integer; safecall;
  end;

...

implementation

...

function TMainForm.GetText: WideString;
begin
  Result := Editor.Text;
end;

procedure TMainForm.SetText(const AValue: WideString);
begin
  Editor.Text := AValue;
end;

// Позвольте мне не приводить остальные методы - они однотипны

...

// Единственное исключение:

function TMainForm.FindText(const SearchStr: WideString; const StartPos, Length: Integer; Options: TEditorSearchTypes): Integer;
var
  Opts: TSearchTypes;
begin
  Opts := [];
  if (Options and esfWholeWord) <> 0 then
    Include(Opts, stWholeWord);
  if (Options and esfMatchCase) <> 0 then
    Include(Opts, stMatchCase);
  Result := Editor.FindText(SearchStr, StartPos, Length, Opts);
end;

...

end.

Как будет выглядеть регистрация интерфейса в менеджере плагинов? А никак - она у нас уже есть:

procedure TMainForm.FormCreate(Sender: TObject);
begin
  SetErrorMode(SetErrorMode(0) or SEM_NOOPENFILEERRORBOX or SEM_FAILCRITICALERRORS);
  Plugins.SetVersion(1);
  Plugins.RegisterServiceProvider(Self); // <- тыц-тыц
  Plugins.LoadPlugins(ExtractFilePath(ParamStr(0)) + 'Plugins', SPluginExt);
  BuildFilterList;

  ...
end;

Обратите внимание, что мы регистрируем не конкретный интерфейс, а объект - поставщик интерфейсов. Т.е. единожды зарегистрировав форму, мы отдаём плагинам все её интерфейсы. Т.е. теперь нам достаточно просто реализовывать в форме интерфейсы - и они автоматически будут доступны плагинами.

Теперь сам плагин:

library HTMLConvert;

uses
  Windows,
  SysUtils,
  Classes,
  ActiveX,
  AxCtrls,
  PluginAPI in 'PluginAPI\Headers\PluginAPI.pas';

{$R *.res}
{$E .rep}

type
  TPlugin = class(TInterfacedObject, IUnknown, IDestroyNotify, INotifyEvent)
  private
    FCore: ICore;
    FMenuItem: IMenuItem;
    procedure Delete; safecall;
    procedure Execute(Sender: IInterface); safecall;
  public
    constructor Create(const ACore: ICore);
    destructor Destroy; override;
  end;

{ TPlugin }

constructor TPlugin.Create(const ACore: ICore);
var
  Manager: IMenuManager;
begin
  inherited Create;
  FCore := ACore;
  Assert(FCore.Version >= 1);

  if Supports(FCore, IMenuManager, Manager) then
  begin
    FMenuItem := Manager.CreateMenuItem;
    FMenuItem.Caption := 'Вставить дату';
    FMenuItem.Hint := 'Вставляет в документ текущую дату и время в местном формате';
    FMenuItem.Enabled := True;
    FMenuItem.Checked := False;
    FMenuItem.RegisterExecuteHandler(Self);
  end;
end;

procedure TPlugin.Delete;
var
  Manager: IMenuManager;
begin
  if Assigned(FMenuItem) and
     Supports(FCore, IMenuManager, Manager) then
    Manager.DeleteMenuItem(FMenuItem);
end;

destructor TPlugin.Destroy;
begin
  Delete;
  inherited;
end;

procedure TPlugin.Execute(Sender: IInterface);
var
  Editor: IEditor;
begin
  if not Supports(FCore, IEditor, Editor) then
    Exit;

  Editor.SelText := DateTimeToStr(Now);
end;

// _________________________________________________________________

function Init(const ACore: ICore): IUnknown; safecall;
begin
  Result := TPlugin.Create(ACore);
end;

procedure Done; safecall;
begin

end;

exports
  Init name SPluginInitFuncName,
  Done name SPluginDoneFuncName;

end.

Этот пример ещё проще предыдущего: у нас всего один пункт меню, а значит нам не нужен вспомогательный объект. Реакцию на щелчок может взять на себя сам TPlugin.

Единственный интересный момент тут - новый интерфейс IDestroyNotify:

type
  IDestroyNotify = interface
  ['{B50C8ABE-A10A-4BD9-AA17-0311326FE1A6}']
    procedure Delete; safecall;
  end;

Я думаю, вы узнали его - я говорил про этот метод выше, хотя и выбрал в тот раз другой способ. Как я говорил, этот способ используется для разрешения проблемы циклических ссылок.

Упражнение: где в этом примере циклическая ссылка? Зачем понадобился интерфейс IDestroyNotify в этом примере? И почему мы обошлись без него в предыдущем плагине? В чём отличие двух ситуаций?

Пару слов об интерфейсе редактора: в данном примере я сделал его практически зеркалом RichEdit-а из программы, но это вовсе не обязательно: вы можете добавлять методы, которых оригинальный объект не имеет. Подумайте, какие операции могут понадобится плагинам к вашей программе, и введите вспомогательные методы для этого.

Сам же интерфейс описывается тривиально. Хочу лишь напомнить про установленные нами в первой части правила. При создании интерфейсов нужно не забывать добавлять safecall, нужно не забывать изменять типы данных (String на WideString, Boolean на BOOL и т.п.) - т.е. никаких Delphi-типов у вас быть не должно.

И в заключение я хотел бы обсудить ещё вот какой вопрос. В последнем примере я создал интерфейс IEditor, где ввёл всего несколько методов для управления редактором. Это означает, что возможности плагинов ограничиваются возможностями интерфейса, которого вы им выдаёте. Т.е. если вы хотите иметь мощные плагины - вы должны дать им много интерфейсов с кучей методов, которые выставят наружу внутренности вашей программы. Чем больше вы сделаете интерфейсов, тем мощнее будут плагины. В примере я схалявил, реализовав всего несколько методов для редактора. В частности, я не создал ни одного метода для управления атрибутами текста (жирный, курсив и т.п.).

Плюсы этого подхода: вы явно контролируете то, что будет доступно плагинам. Кроме того, вид для плагинов не обязан отражать реальную структуру вашей программы (к примеру, в нашем примере менеджер меню и редактор реализовывались формой, хотя по факту это TMainMenu и TRichEdit - разные объекты). Минусы: вам нужно вручную писать код-переходник. И чем мощнее вы хотите сделать возможности плагинов, тем больше кода вам придётся писать.

И если ваша программа обладает очень сложным пользовательским интерфейсом, а вы хотите дать плагинам полный доступ к нему, плюс к тому же работа с пользовательским интерфейсом программы будет основной задачей для плагинов - то полноценные плагины будут не самой удачной архитектурой. Я говорил про это во вступлении к первой части. Более удачным выбором будут скрипты.

А если вы всё же используете плагины в виде библиотек, а не скрипты, то помимо указанного способа (проектирование интерфейсов и написание кода-обёртки) есть ещё один способ: можно дать плагинам прямой доступ к какому-то элементу программы. К примеру, для нашего редактора это может быть либо описатель (свойство Handle), либо уже готовый системный интерфейс IRichEditOle. Вы можете передать плагину одну из этих вещей, а плагин сможет работать с ней, используя системный API. Разумеется, вы не можете передавать плагину сам объект TRichEdit, потому что это - класс языка Delphi, он не "кросс-языковен" (чёрт, как тут иначе сказать?).

Плюсы такого подхода: ничего не надо писать, просто передайте описатель. Минусы: вы не сможете контролировать плагин. К примеру, плагин сможет просто скрыть редактор или вовсе его удалить. Потому что у него есть описатель редактора, а значит - полный и неконтролируемый доступ. С другой стороны, с подходом из примера выше плагин не сможет сделать это (скрытие или удаление редактора) - потому что мы не дали ему методов. Второй минус - сильная зависимость от реализации программы. К примеру, вот выставили мы плагинам наш редактор, который сейчас у нас - RichEdit. А в следующей версии программы мы поняли, что нам мало RichEdit-а. Поэтому мы заменили его на custom-контрол с собственной прорисовкой. Если мы используем свои интерфейсы - нет проблем, плагины даже не заметят подмены. А если мы передаём описатель редактора плагинам, то... опс, (старый) плагин ожидает увидеть RichEdit, а получает что-то непонятное.

Скачать пример.

На следующий раз у нас остаётся взаимодействие плагинов друг с другом, пользовательский интерфейс в плагинах, а также обработка ошибок и отладка.

Разработка системы плагинов в Delphi, часть 2: разработка API

2012-01-08T00:18:00.000+04:00

Первая часть.

В этой части мы рассмотрим реализацию функциональности плагинов.

Для начала я напомню, что в качестве демонстрационного приложения я использовал программу-пример из комплекта демок Delphi - RichEdit Demo. Программа представляет собой простенький текстовый редактор типа WordPad:

Напомню, что в прошлый раз мы создали в этой программе инфраструктуру для плагинов и написали пустой плагин. Теперь настало время для реализации чего-то полезного.

Спецификация

Да, я знаю, что это скучно. Но начать нужно именно с более-менее формального изложения того, что мы хотим получить от плагинов. В каком-то виде в дальнейшем это войдёт в вашу документацию по разработке плагинов, но сейчас нам нужно иметь что-то, от чего мы будем отталкиваться.

Итак, что же нам можно сделать? В качестве примера я предлагаю разработать плагины импорта/экспорта. Посмотрите: если вы в программе выберите File/Save as или File/Open - вы увидите диалоги выбора файлов с двумя возможными форматами: RTF и TXT. Т.е. либо Rich Text, либо просто текст. Но что если мы хотим сохранять наш файл в HTML? Как насчёт DOC? Ну или хотя бы ODT? И экспорт в PDF был бы полезен... Понятно, что в самой программе мы не можем заранее предусмотреть все возможные форматы файлов - ведь некоторые из форматов могут просто не существовать в момент создания программы, а появиться позже. Поскольку у нас нет машины времени, мы не можем предсказать, какие форматы будут полезны пользователям нашей программы.

Поэтому я предлагаю ввести в программу плагины импорта и экспорта. Каждый плагин будет поддерживать один какой-то формат файлов, которого нет в списке по умолчанию (RTF и TXT). Плагин экспорта должен уметь создать такой файл по RTF тексту. Плагин импорта должен уметь распарсить входной файл и создать по нему RTF (т.е. преобразовать одно в другое).

Понятно, что задачи это не всегда тривиальные, различные по сложности. К примеру, одно дело - сгенерировать HTML файл, а совсем другое - его распарсить. Некоторые задачи отличаются повышенной сложностью - например, импорт формата DOC. Который мало того, что является закрытым форматом (т.е. официально не описан), так ещё и обладает неимоверно сложной внутренней структорой.

Как видите, эти задачи - "тяжеловесные". Они хорошо решаются на обычных языках программирования, где у вас есть возможность использовать мощные языковые средства, подключать готовые библиотеки кода, взаимодействовать с другими программами, но они слабо подходят для их решения на скриптовых языках ("легковесные плагины").

Итак, сейчас я сформулировал "чего мы хотим". Теперь надо подумать про то, что нам может понадобится для реализации.

Давайте введём правило, что готовые плагины экспорта/импорта наша программа будет автоматически загружать при запуске из подпапки Plugins. Для этого у нас уже есть готовая инфраструктура, разработанная в прошлой части. На самом деле, мы там реализовали даже больше чем надо - там есть и выборочная загрузка и т.п.

Окей, что дальше? Тут надо рассуждать так: что должен делать плагин после своей загрузки? Ну, как минимум в диалоге сохранения/загрузки должны появится пункты "сохранить в формат XXX", где XXX - это формат, поддерживаемый плагином. Ага, значит плагин должен сообщить ядру две вещи:

Расширение файла (для использования в фильтре). Например, "htm". Или маску файлов. Например, "*.htm".
Читабельное название формата файлов (для показа в списке выбора файлов). Например, "Гипертекстовые документы (HTM/HTML)".

Отлично, первый шаг есть. Формализовать его кодом мы будем чуть позже. А сейчас будем думать дальше: что ещё потребуется от плагина? Ну, когда его пользователь выберет плагин в диалоге выбора файлов, ядро должно вызвать плагин для экспорта или импорта RTF. Это значит, что плагин экспорта должен предоставлять функцию экспорта, а плагин импорта - функцию импорта. Ядро вызовет эту функцию, когда пользователь нажмёт на кнопку "OK" в диалоге выбора файлов. Соответственно, ядро передаст туда как минимум имя файла, а также... что?

Рассмотрим ситуацию с плагинами экспорта. У нас в программе есть Rich Edit. Нам нужно как-то передать его плагину, чтобы тот сохранил RTF-текст в какой-то свой формат. Как это можно сделать? Ну, можно тупо взять и передать сам Rich Edit. Это будет работать, но это - плохое решение. Почему? Потому что вы выставляете плагину свои внутренности. По идее, плагин занимается преобразованием RTF в другой формат. Нужен ему для этого визуальный редактор? Нет, ему нужен RTF-текст. Или вы можете посмотреть на это с такой стороны: предположим вы делаете консольный конвертер файлов. Будет ли в нём TRichEdit? Нет, откуда? Ведь у консольной программы нет GUI. Т.е. все эти мысли намекают вам, что передача RichEdit-а плагину - не самое удачное решение.

Что же делать? Как нам ещё можно передать данные плагину? Как-как - с использованием потоков данных, конечно же! RichEdit может сохранить своё содержание (RTF текст) в поток данных, а мы затем можем передать этот поток данных плагину. Плагин может прочитать RTF-текст и преобразовать его как душе угодно.

Аналогичные рассуждения верны и для плагинов импорта, с той лишь разницей, что у них ввод и вывод поменяны местами.

Примечание: аналогичным образом, вместо имени файла можно использовать потоки данных. Таким образом, ядро может передавать плагину входной поток данных и выходной поток данных. Задача плагина - преобразовать одно в другое. А уж то, к чему привязывать эти потоки данных (к файлу ли или RichEdit-у на форме) - забота ядра, а не плагина. Тем не менее, в примере я буду использовать поток с одной стороны и имя файла с другой стороны.

Что ещё? Ну вроде как и всё. Этого будет достаточно для реализации простых плагинов иморта и экспорта. Сейчас мы только что набросали черновую спецификацию работы наших плагинов. Как видите, это было несложно.

Формализация в коде

Теперь по этому словесному описанию надо создать код.

Предварительно я напомню, что здесь и далее я буду писать заголовочники сразу в виде .pas файлов, но в реальности вам нужно создавать их в редакторе библиотеки типов, если вы хотите распространять их в другие языки. Я подробно разжевал эту мысль в первой части, так что не буду повторять её здесь.

Итак, начнём с информационной части - нам нужно сообщить ядру расширение или маску, а также текстовое описание. Нет проблем:

IPlugin = interface
['{D6B90C88-647D-4265-9052-2EE1BD274979}']
// private
  function GetMask: WideString;
  function GetDescription: WideString;
// public
  property Mask: WideString read GetMask;
  property Description: WideString read GetDescription;
end;

Как видите, эта часть - общая для плагинов обоих типов (и экспорта и импорта).

Далее - плагину экспорта нужна функция экспорта, а плагину импорта - функция импорта. Без проблем - как описали, так и пишем:

IExportPlugin = interface
['{09428378-34BA-4326-8550-BF1CA72FDF53}']
  procedure ExportRTF(const ARTF: IStream; const AFileName: WideString); safecall;
end;

IImportPlugin = interface
['{6C85B093-7AAF-4EF0-B98E-D9DBDE950718}']
  procedure ImportRTF(const AFileName: WideString; const ARTF: IStream); safecall;
end;

Как видите, наши слова из предыдущего раздела практически буквально ложатся на код.

Вот, собственно, и всё. Заголовочники готовы. Когда вы словами описали, чего вы хотите, написать код - дело пяти секунд. Если же вы не вполне представляете себе, чего вы хотите, этот шаг будет нетривиален.

Окончательное формирование контракта

После того, как вы получили код в заголовочниках - вы получили "синтаксический контракт". Т.е. набор правил, которому нужно следовать плагину и ядру, чтобы успешно понять друг друга. Но это - ещё не всё. Теперь вам нужно создать "семантический контракт" - набор правил, говорящий про то, как использовать этот код.

Я помещу этот раздел до начала реализации - просто чтобы у нас сразу был полностью готовый контракт ещё до того, как мы начнём писать код. В реальности же, ничего страшного если некоторые детали контракта будут выясняться лишь по ходу написания реализации. Главное - чтобы они вообще появлялись.

Возможно, сказанное выше сейчас не очень понятно - что такое я имею в виду? На самом деле, тут ничего сложного нет. Я имею в виду, что вы должны явно написать правила типа таких: "имя файла не должно быть пустой строкой". Вам, как создателю всей архитектуры программы, это может быть очевидно - вы же знаете весь свой код. Но сторонним разработчикам это может быть не очевидно. Что если пустое имя файла в плагине импорта означает создание пустого документа? Хм, об этом вы не подумали. Или, вот, другой пример: если в функцию импорта/экспорта передали поток данных - надо ли его позиционировать на начало перед работой или нужно работать с текущей позиции? Тоже интересный вопрос. А вот и ещё один: имя файла, передаваемое в функцию импорта/экспорта - всегда ли оно абсолютное и полное? Не может ли это быть просто 'MyFileName.htm'? Ведь последнее означает, что функция импорта/экспорта уже больше не может свободно распоряжаться текущим каталогом. И такой вопрос: надо ли плагину экспорта выводить предупреждение о перезаписи файла, если файл-назначение уже существует? Или же предупреждение вынесет ядро?

Я привёл пример нескольких вопросов, на которые вам, как разработчику системы плагинов, необходимо ответить. По каждому вопросу вам нужно принять решение (к примеру: "Имя файла не пусто и всегда содержит полный и абсолютный путь до файла. Файл для импорта всегда существует, а файл для экспорта может как существовать, так и не существовать. В первом случае функция экспорта обязана безусловно перезаписать файл, не выводя подтверждения. Поток данных всегда передаётся спозиционированным на своё начало, данные для работы плагина начинаются с начала потока данных и заканчиваются в его конце"). Вы можете выбирать различные решения указанных вопросов - но, какие бы решения вы ни выбрали, вы обязаны задокументировать их в документации к плагинам.

К примеру, в вашей документации к плагинам могла бы быть такая статья:

IExportPlugin.ExportRTF

Экспортирует текст программы в сторонний формат файлов.

Синтаксис

procedure ExportRTF(

const ARTF: IStream;

const AFileName: WideString

); safecall;

Параметры

ARTF [входной]

Тип: IStream

Поток данных, содержащий RTF-текст из редактора программы. Поток всегда спозиционирован на начало.

AFileName [выходной]

Тип: BSTR

Абсолютное имя файла-назначения. Файл может существовать. В этом случае функция должна его перезаписать.

Возвращаемое значение

Нет. Ошибки возвращаются стандартным способом.

Примечания

Эту функцию реализует плагин экспорта, чтобы производить экспорт текста.

Ядро вызывает эту функцию, когда пользователь выбирает плагин в диалоге выбора файлов и нажимает OK. Ядро передаёт функции текущий RTF-текст и имя файла, указанное пользователем (имя файла преобразуется в абсолютный формат). Функция должна создать указанный файл (а при его наличии – перезаписать) и сохранить в него переданный первым параметром RTF-текст, преобразовав его в нужный формат.

Примеры

Пример использования можно увидеть в статье Пример реализации плагина экспорта.

Требования

Версия ядра

1

Заголовоный файл

PluginAPI.tlb

См. также

IImportPlugin.ImportRTF

(Да, это документация с закосом под MSDN)

Конечно же, вы можете придерживаться любого другого стиля оформления документации, в том числе вы можете готовить её не в виде CHM/HTML файлов, а писать в комментариях прямо в заголовочниках. Всё это - вторичные детали. Самое главное тут - что она (эта документация) вообще должна быть. Потому что в ней написаны такие вещи ("семантика"), которые не выражены в коде.

Так что, как бы вы ни оформляли свою документацию, проследите чтобы в ней было:

(Опционально) Краткое описание метода, что он делает. Эта часть нужна, чтобы быстро ухватить суть метода. В принципе, поскольку у вас есть подробное описание (см. ниже), то её можно не писать. Но её наличие позволяет более эффективно работать с документацией.
(Опционально) Синтаксис метода (копия из заголовочника). Не обязательно, ведь код можно посмотреть в заголовочниках, но лучше приводить - исключительно для удобства (не надо ещё куда-то лазить, чтобы увидеть синтаксис). Всегда отсутствует в документации, написанной прямо в заголовочниках (по очевидным причинам).
(Обязательно) Описание каждого параметра и возвращаемого значения функции. Опишите, какой параметр входной, какой выходной, какие ограничения вы задаёте для параметров, какие значения он может принимать, а какие - не может. Как метод должен реагировать на специальные случаи (если они есть).
(Обязательно) Обработка ошибок. Как метод сообщает об ошибках. Какие есть специальные случаи, которые вызывающий может хотеть явно обработать.
(Обязательно) Подробное описание метода и его работы. Нужно сказать, когда он вызывается, что он делает, что должен выдавать. Описать типичное использование, краевые случаи и возможные подводные камни.
(Опционально) Пример использования или ссылка на него.
(Обязательно) Требования - т.е. в какой версии сервера (ядра) появился этот метод и где искать его описание. Понятно, что в первом варианте вашей системы плагинов у вас каждый метод будет присутствовать, начиная с первой версии ядра (просто потому, что другой версии у вас нет). И в этом случае этот раздел можно не писать из-за его очевидности. Но в дальнейшем, когда вы будете расширять свою систему и у вас появятся новые методы, этот раздел всё равно нужно будет добавить.
(Опционально) Ссылки на тесно связанные или аналогичные методы, плюс ссылки на обобщающий материал (если есть) или корневой раздел.

Небольшое замечание по поводу входных и выходных параметров. Дело в том, что этот термин может использоваться в двух разных смыслах. Во-первых, есть очевидный смысл: P: T, const P: T - входные параметры, out P: T - выходной параметр, а var P: T - входной-выходной. Это - синтаксический смысл. Он очевидно следует из кода метода. Поэтому лично я считаю, что этот смысл не нужно дублировать ещё и словами в документации (вы ведь привели синтаксис метода, дааа?).

Но есть и другой смысл, скорее семантический. К примеру, в нашем методе первый параметр у нас формирует ядро, плагин из него должен извлечь информацию. Т.е. это как бы "входной" параметр. С другой стороны, второй параметр, хотя по синтаксису он чисто "входной" - но подразумевается, что плагин должен записать в этот файл информацию, "вывести её". И вот с этой точки зрения параметр может рассматриваться как "выходной". Так вот, этот, второй смысл, я и предлагаю указывать в документации. Потому что первый смысл и так у нас есть - он выражен в синтаксисе метода. А вот второй смысл там не содержится - он лишь следует из описания параметра. Т.е. в каком-то смысле, это является аналогом "краткого заголовка" для параметра - аналогично тому, как краткое пояснение метода является обобщением его подробного описания.

Итого, ваш контракт плагинов будет состоять из двух частей: синтаксиса (заголовочники) и семантики (документация).

Реализация

К этому моменту у нас на руках есть полностью формализированный комплект правил для плагинов, так что написать код сейчас будет очень просто. Но на практике вы можете приступить к этому пункту раньше, чем завершите подготовку контракта. Поэтому это может быть сложнее.

В качестве примера сейчас мы напишем несколько плагинов экспорта-импорта, а также научим ядро работать с ними. Поскольку эта статья - про плагины, а не про вопросы работы с RTF-текстом, то я ограничусь лишь простыми, тривиальными примерами. Чтобы было хоть чуточку интересно, я предлагаю уже существующие возможности (импорт/экспорт в RTF и TXT) тоже оформить в виде плагинов. Это позволит мне продемонстрировать работу с плагинами, не отвлекаясь на вопросы преобразования RTF - это сама по себе непростая задача. По идее, если вы захотите развить этот пример и сделать импорт/экспорт в другие форматы, вам придётся выполнить кучу работы. Во-первых, вам нужно прочитать входной документ и распарсить его, создав модель документа в памяти. Модель - это значит что документ будет представлен объектами "документ", "абзац", "строка", "параметры шрифта" и т.п. Это делается, чтобы с документом можно было удобно работать. И при этом вам нужно следить, что вы покрываете все случаи, описанные в спецификации формата, вас ожидают волнительные вопросы работы с кодировками и т.д. Когда преобразование выполнено, то остаётся пройтись по модели документа и выполнить её "сборку" в документ другого формата. В общем, если вас заинтересует развитие этого примера, то в сети можно найти готовый код для парсинга RTF и других форматов. Альтернативно можно попробовать делать преобразование RTF как замену строк - этот подход основывается на том факте, что RTF - это текстовый формат, вроде HTML. Т.е. вы можете получить содержимое в виде строки, а затем серией замен сменить атрибуты RTF на, скажем, тэги HTML. Или вы можете просто использовать уже написанный и готовый код. В этом случае ваша задача по написанию плагина будет заключаться в инкапсуляции готовой библиотеки кода в виде плагина к программе. В любом случае, как видите, всё это достаточно трудоёмкие задачи - и именно поэтому здесь они не рассматриваются.

Итак, начнём с ядра:

procedure TMainForm.FormCreate(Sender: TObject);
begin
  SetErrorMode(SetErrorMode(0) or SEM_NOOPENFILEERRORBOX or SEM_FAILCRITICALERRORS);
  // Загрузка всех плагинов. Подразумевается, что они лежат в под-папке Plugins
  Plugins.LoadPlugins(ExtractFilePath(ParamStr(0)) + 'Plugins');

  ...
end;

Это - загрузка плагинов. Тут ничего особенного нет, все плагины грузятся автоматически и скопом, не различаясь по типу.

В дальнейшем нам потребуется показывать загруженные плагины в диалогах сохранения/открытия, поэтому предлагаю сразу же после загрузки плагинов подготовить диалоги. Мы можем это сделать, потому что список плагинов у нас не меняется. Если бы мы добавили в программу возможность динамически загружать плагины по указке пользователя (замечу, что наша архитектура это позволяет, просто мы не выставляем эту возможность в данном примере), то нам нужно было бы это делать каждый раз перед открытием диалога.

procedure TMainForm.FormCreate(Sender: TObject);
begin
  SetErrorMode(SetErrorMode(0) or SEM_NOOPENFILEERRORBOX or SEM_FAILCRITICALERRORS);
  // Загрузка всех плагинов. Подразумевается, что они лежат в под-папке Plugins
  Plugins.LoadPlugins(ExtractFilePath(ParamStr(0)) + 'Plugins');

  BuildFilterList;

  ...
end;

procedure TMainForm.BuildFilterList;

  function BuildFilter(const AInterface: TGUID): String;
  var
    X, Y: Integer;
    Intf: IInterface;
  begin
    Result := '';
    Y := 0;
    // Отбираем только нужные плагины и заносим их в список
    for X := 0 to Plugins.Count - 1 do
      if Supports(Plugins[X], AInterface, Intf) then
      begin
        Result := Result + Plugins[X].Description + '|' + Plugins[X].Mask + '|';
        Plugins[X].FilterIndex := Y;
        Inc(Y);
        Intf := nil;
      end;
    // Удалили лишний | в конце строки
    SetLength(Result, Length(Result) - 1);
  end;

begin
  OpenDialog.Filter := BuildFilter(IImportPlugin);
  SaveDialog.Filter := BuildFilter(IExportPlugin);

  OpenDialog.FilterIndex := 1;
  SaveDialog.FilterIndex := 1;
end;

Тут мы два раза проходимся по общему списку плагинов, отбирая плагины по типам и занося их в список для диалогов. Я воспользовался той же техникой, что и в прошлый раз - спроецировав плагин на локальный тип данных, так что работа с плагинами ничем не отличается от работы с локальными объектами. Я не буду приводить изменения в коде менеджера плагинов - все изменения делаются по аналогии, как и в прошлый раз. Вы можете посмотреть полный исходный код в примере к статье (см. ниже).

Единственное, на что я хочу обратить момент прямо сейчас - нам нужно как-то связать плагин со строкой в фильтре диалога. Т.е. вот сейчас мы добавили плагин в диалог - это хорошо. А что нам делать потом, когда пользователь прикажет программе сохранить файл именно в этот формат? Как нам найти нужный плагин? По какому признаку их отличать?

Тут есть несколько разных подходов. Давайте я кратенько их опишу.

Подход первый: опознавать плагин по его характеристике. Например, по маске. Или по описанию. Или по тому и другому. Это будет работать, если эта характеристика - уникальна. Плюсы: дополнительно ничего делать не надо, минусы: не всегда такая характеристика есть. В данном случае эта характеристика не уникальна, потому что теоретически никто не мешает нам установить два плагина экспорта в PDF: плагин от Васи и плагин от Пети.

Подход второй: создать уникальную характеристику и отслеживать по ней. К примеру, это ID плагина, который имеет уникальный GUID. Такой ID уже есть в нашем предыдущем примере с плагинами, так что мы могли бы использовать его. И вообще-то обычно так вам и нужно поступать. Но в данном конкретном случае это не очень удобно - потому что нам нужно хранить этот ID плагина в фильтре диалога. Т.е. прежде чем использовать этот подход, надо сначала изменить диалог - мы же практикуем правильные подходы, а не "поставь распорку сбоку - ничего не развалится" (т.е. ведение списка ID отдельно от диалога). Плюсы: подходит всегда, гарантированная уникальность. Минусы: целевой объект должен поддерживать возможность сохранять ID плагина, т.е. обычно требуется доработка существующих классов.

Третий, не очень правильный, подход: ввести "обратный идентфикатор" и заставить плагин помнить нужную информацию. Именно этот подход я применил в примере выше. Плюсы: не нужно модифицировать сторонний класс, минусы: зависимость менеджера плагинов от использующего его кода, кроме того, этот метод не всегда применим. Тут надо заметить, что сам плагин (разумеется!) не должен ничего знать про то, как ядро его использует. Какой там у него индекс в диалоге сохранения - не его ума дело, а ядра. Поэтому, конечно же, эту информацию передавать самому плагину нельзя. Но поскольку у нас есть менеджер плагинов и он отслеживает информацию о плагинах (вроде его индекса, описателя библиотеки и имени файла - всех этих вещей на руках у плагина нет), то почему бы не дать ему отслеживать ещё один дополнительный кусочек информации? Именно таким кусочком в моём примере является (новое) свойство FilterIndex.

Дополнительно отмечу четвёртый (тоже не совсем правильный) подход: идентификация плагинов по индексу в менеджере плагинов. Плюсы: идентификатор можно записать в свойства типа Tag, Objects, lpParam и т.п. (т.е. не нужна доработка классов), минусы: эта схема не пригодна при динамической загрузке/выгрузке, т.к. индексы при этом могут меняться.

Ладно, разобрались. Далее, сам экспорт:

procedure TMainForm.FileSaveAs(Sender: TObject);
var
  Plugin: IExportPlugin;
  RTFStream: IStream;
  Stream: TStream;
begin
  if SaveDialog.Execute then
  begin
    if FileExists(SaveDialog.FileName) then
      if MessageDlg(Format(sOverWrite, [SaveDialog.FileName]),
        mtConfirmation, mbYesNoCancel, 0) <> idYes then Exit;

    // Ищем плагин
    if not FindPlugin(SaveDialog.FilterIndex - 1 { у FilterIndex отсчёт с 1, корректируем},
                      IExportPlugin, Plugin) then
      Exit;

    // Готовим данные для экспорта
    Stream := TMemoryStream.Create;
    RTFStream := TStreamAdapter.Create(Stream, soOwned);
    Editor.Lines.SaveToStream(Stream);
    Stream.Position := 0;

    // Вызываем экспорт
    Plugin.ExportRTF(RTFStream, SaveDialog.FileName);

    // Учёт (без изменений)
    SetFileName(SaveDialog.FileName);
    Editor.Modified := False;
    SetModified(False);
  end;
end;

...и импорт:

procedure TMainForm.FileOpen(Sender: TObject);
var
  Stream: TStream;
  RTFStream: IStream;
  Plugin: IImportPlugin;
begin
  CheckFileSave;
  SetFileName(sUntitled);  // <- указали, что это - новый документ
  if OpenDialog.Execute then
  begin
    // Импорт
    Stream := TMemoryStream.Create;
    RTFStream := TStreamAdapter.Create(Stream, soOwned);
    if not FindPlugin(OpenDialog.FilterIndex - 1, IImportPlugin, Plugin) then
      Exit;
    Plugin.ImportRTF(OpenDialog.FileName, RTFStream);

    // Обработка данных импорта
    Stream.Position := 0;
    Editor.Lines.LoadFromStream(Stream);

    // Учёт
    Editor.SetFocus;
    Editor.Modified := False;
    SetModified(False);
    Editor.ReadOnly := ofReadOnly in OpenDialog.Options;
  end;
end;

А также команда "просто Save":

procedure TMainForm.FileSave(Sender: TObject);
var
  Plugin: IExportPlugin;
  RTFStream: IStream;
  Stream: TStream;
begin
  if FFileName = sUntitled then
    FileSaveAs(Sender)
  else
  begin
    // Ищем плагин
    if not FindPlugin(SaveDialog.FilterIndex - 1, IExportPlugin, Plugin) then
      Exit; 

    // Вызываем экспорт
    Stream := TMemoryStream.Create;
    RTFStream := TStreamAdapter.Create(Stream, soOwned);
    Editor.Lines.SaveToStream(Stream);
    Stream.Position := 0;
    Plugin.ExportRTF(RTFStream, FFileName);

    Editor.Modified := False;
    SetModified(False);
  end;
end;

Функция FindPlugin тривиальна (она возвращает запрошенный интерфейс у плагина с заданным индексом фильтра):

function TMainForm.FindPlugin(const AIndex: Integer; const AGUID: TGUID; out Obj): Boolean;
var
  X: Integer;
begin
  Result := False;
  for X := 0 to Plugins.Count - 1 do
    if Plugins[X].FilterIndex = AIndex then
    begin
      Result := Supports(Plugins[X], AGUID, Obj);
      if Result then
        Break;
    end;
end;

Здесь нужно обратить внимание на фундаментальное изменение в поведении программы. Раньше, когда плагинов в программе у нас не было, мы могли загрузить файл и нажать на кнопку "Save". И это действие сохранило бы файл в оригинальном формате. Но когда мы перевели загрузку/сохранение на плагины - мы этого сделать не можем. Потому что у нас сейчас нет информации о связи плагинов импорта и экспорта. И если у нас установлен плагин импорта, скажем, из HTML, то это не значит, что установлен и плагин экспорта в HTML. Иными словами, операция может быть односторонней. Поэтому в данном примере при открытии файла мы помечаем его как ещё не сохранённый - и тогда при сохранении мы покажем диалог выбора имени файла и плагина для экспорта.

А чтобы реализовать исходное поведение, нам нужно приложить больше усилий - нужно придумать способ ассоциации плагинов импорта с плагинами экспорта. Делать это можно разными способами, но сейчас я не буду рассматривать этот вопрос. Пока нам хватит текущего материала.

Я приведу некоторые изменения в менеджере плагинов, которые я сделал для этого примера:

type
  IPlugin = interface
  // protected
    ...
    function GetMask: String;
    function GetDescription: String;
    function GetFilterIndex: Integer;
    procedure SetFilterIndex(const AValue: Integer);
  // public
    ...
    property Mask: String read GetMask;
    property Description: String read GetDescription;

    property FilterIndex: Integer read GetFilterIndex write SetFilterIndex;
  end;

...

  TPlugin = class(TInterfacedObject, IUnknown, IPlugin)
  private
    ...
    FFilterIndex: Integer;
    FPlugin: PluginAPI.IPlugin;
    FInfoRetrieved: Boolean;
    FMask: String;
    FDescription: String;
    procedure GetInfo;
  protected
    ...
    function GetMask: String;
    function GetDescription: String;
    function GetFilterIndex: Integer;
    procedure SetFilterIndex(const AValue: Integer);
    function QueryInterface(const IID: TGUID; out Obj): HResult; stdcall;
  public
    ...
  end;

  ...

procedure TPlugin.GetInfo;
begin
  if FInfoRetrieved then
    Exit;
  FMask := FPlugin.Mask;
  FDescription := FPlugin.Description;
  FInfoRetrieved := True;
end;

function TPlugin.GetFilterIndex: Integer;
begin
  Result := FFilterIndex;
end;

procedure TPlugin.SetFilterIndex(const AValue: Integer);
begin
  FFilterIndex := AValue;
end;

function TPlugin.QueryInterface(const IID: TGUID; out Obj): HResult;
begin
  Result := inherited QueryInterface(IID, Obj);
  if Failed(Result) then
    Result := FPlugin.QueryInterface(IID, Obj);
end;

Почти все изменения я уже обсудил - это и дублирование Mask/Description и новое поле FilterIndex, не передаваемое плагину. Осталось пояснить только код с QueryInterface. Нужен он вот зачем: нашей программе нужен от плагина не только IPlugin (функциональность которого и так выставляется наружу менеджером плагинов), но и IExportPlugin/IImportPlugin. Как программа может их получить? По идее, их нужно запрашивать у интерфейса плагина, который вернула функция инициализации плагина. Этот интерфейс хранится в менеджере плагинов внутри класса TPlugin - в поле FPlugin. Чтобы выставить его наружу есть два варианта: простой и красивый.

Простой вариант выглядит так:

type
  IPlugin = interface
  ...
    function GetIntf: PluginAPI.IPlugin;
  ...
    property Intf: PluginAPI.IPlugin read GetIntf;
  end;

...

  TPlugin = class(TInterfacedObject, IUnknown, IPlugin) 
  private
    FPlugin: PluginAPI.IPlugin;
  ...
    function GetIntf: PluginAPI.IPlugin;
  ...  
  end;

...

function TPlugin.GetIntf: PluginAPI.IPlugin;
begin
  Result := FPlugin;
end;

(да, я знаю: у меня два разных интерфейса называются одним именем; наверное, это не очень удачно, но другого подходящего имени мне в голову не пришло, а они не пересекаются, так что я оставил так, но вы можете использовать разные имена, чтобы не запутаться)

И тогда работа с плагином выглядела бы так:

for X := 0 to Plugins.Count - 1 do
  if Supports(Plugins[X].Intf, IExportPlugin, ExportPlugin) then
    ...

Т.е. получается, что мы ввели лишний уровень косвенности - Intf. Этот способ прост, потому что очевиден: мы просто открыли доступ к внутреннему полю.

Но есть и другой способ, более красивый - именно его я и использовал. Смысл его заключается в том, чтобы разрешить получать интерфейсы плагина не через плагин, а через его обёртку в менеджере плагинов. Именно этим занимается переопределённый метод QueryInterface. Логика у него чрезвычайно простая: сперва вызовем унаследованную реализацию. Нашла она запрашиваемый интерфейс? Если да - то выходим. В этой ситуации кто-то запросил интерфейс оболочки плагина. Если же унаследованная реализация ничего не нашла, то это означает, что оболочка плагина этот интерфейс не реализует. Но тогда, быть может, нас спрашивают не о нашем интерфейсе, а интерфейсе плагина? Тогда мы вызовем запрос интерфейса у плагина.

Иными словами, новая реализация QueryInterface делегирует запросы всех неподдерживаемых интерфейсов плагину. Это не значит, что любой вызов будет успешен - в конце концов, плагин не всё же подряд поддерживает. Но эта логика гарантирует, что все поддерживаемые плагином интерфейсы могут быть получены через его обёртку в менеджере плагинов.

С таким подходом мы можем писать код вида:

for X := 0 to Plugins.Count - 1 do
  if Supports(Plugins[X], IExportPlugin, ExportPlugin) then
    ...

Обратите внимание, что к этому моменту обёртка плагина для нас вообще ничем не отличается от самого плагина, с точки зрения вызывающего нет никакой разницы. Со стороны это выглядит так, словно у плагина каким-то "волшебным" образом появились свойства, которых у него на самом деле нет (Index, FileName, FilterIndex и т.п.).

Кстати говоря, в таком простом примере можно было бы вообще объединить IPlugin с IImportPlugin и IExportPlugin, но я специально сделал два интерфейса, чтобы показать как можно запрашивать у плагина разную функциональность, а также чтобы лучше подчеркнуть логику разработки: "нам что-то от плагина надо? - создай интерфейс для этого!"

Давайте теперь перейдём к плагинам. Начнём с плагинов импорта/экспорта для RTF. Они тривиальны, потому что нам не нужно выполнять преобразования потоков данных, а нужно просто тупо скопировать их.

Плагин экспорта:

library ExportRTF;

uses
  SysUtils,
  Classes,
  ActiveX,
  AxCtrls,
  PluginAPI in 'PluginAPI\Headers\PluginAPI.pas';

{$R *.res}
{$E .rep}

type
  TPlugin = class(TInterfacedObject, IUnknown, IPlugin, IExportPlugin)
  private
    FCore: ICore;
  protected
    // IPlugin
    function GetMask: WideString; safecall;
    function GetDescription: WideString; safecall;

    // IExportPlugin
    procedure ExportRTF(const ARTF: IStream; const AFileName: WideString); safecall;
  public
    constructor Create(const ACore: ICore);
  end;

{ TPlugin }

constructor TPlugin.Create(const ACore: ICore);
begin
  inherited Create;
  FCore := ACore;
  Assert(FCore.Version >= 1);
end;

function TPlugin.GetMask: WideString;
begin
  Result := '*.rtf';
end;

function TPlugin.GetDescription: WideString;
begin
  Result := 'Rich Text (RTF)';
end;

procedure TPlugin.ExportRTF(const ARTF: IStream; const AFileName: WideString);
var
  FS: TFileStream;
  RTFStream: TOleStream;
begin
  FS := TFileStream.Create(AFileName, fmCreate or fmShareExclusive);
  try
    RTFStream := TOleStream.Create(ARTF);
    try
      FS.CopyFrom(RTFStream, 0);
    finally
      FreeAndNil(RTFStream);
    end;
  finally
    FreeAndNil(FS);
  end;
end;

// _________________________________________________________________

function Init(const ACore: ICore): IPlugin; safecall;
begin
  Result := TPlugin.Create(ACore);
end;

procedure Done; safecall;
begin

end;

exports
  Init name SPluginInitFuncName,
  Done name SPluginDoneFuncName;

end.

И плагин импорта:

library ImportRTF;

uses
  SysUtils,
  Classes,
  ActiveX,
  AxCtrls,
  PluginAPI in 'PluginAPI\Headers\PluginAPI.pas';

{$R *.res}
{$E .rep}

type
  TPlugin = class(TInterfacedObject, IUnknown, IPlugin, IImportPlugin)
  private
    FCore: ICore;
  protected
    // IPlugin
    function GetMask: WideString; safecall;
    function GetDescription: WideString; safecall;

    // IImportPlugin
    procedure ImportRTF(const AFileName: WideString; const ARTF: IStream); safecall;
  public
    constructor Create(const ACore: ICore);
  end;

{ TPlugin }

constructor TPlugin.Create(const ACore: ICore);
begin
  inherited Create;
  FCore := ACore;
  Assert(FCore.Version >= 1);
end;

function TPlugin.GetMask: WideString;
begin
  Result := '*.rtf';
end;

function TPlugin.GetDescription: WideString;
begin
  Result := 'Rich Text (RTF)';
end;

procedure TPlugin.ImportRTF(const AFileName: WideString; const ARTF: IStream); safecall;
var
  RTFStream: TOleStream;
  FS: TFileStream;
begin
  RTFStream := TOleStream.Create(ARTF);
  try
    FS := TFileStream.Create(AFileName, fmOpenRead or fmShareDenyWrite);
    try
      RTFStream.CopyFrom(FS, 0);
    finally
      FreeAndNil(FS);
    end;
  finally
    FreeAndNil(RTFStream);
  end;
end;

// _________________________________________________________________

function Init(const ACore: ICore): IPlugin; safecall;
begin
  Result := TPlugin.Create(ACore);
end;

procedure Done; safecall;
begin

end;

exports
  Init name SPluginInitFuncName,
  Done name SPluginDoneFuncName;

end.

Как видите, они тривиальны - но лишь потому, что нам не нужно выполнять преобразование данных. Зато на этом простом примере видно, как нужно делать плагины. А если у вас возникнет желание сделать экспорт в HTML, PDF и т.п. - что ж, словами я описал этот процесс выше.

Кстати говоря, обратите внимание, что при выбранной схеме один и тот же плагин может быть одновременно и плагином импорта и плагином экспорта - для этого ему всего лишь нужно реализовывать два интерфейса одновременно (и IImportPlugin и IExportPlugin). А ещё надо заметить, что если разрешить такую ситуацию, то наш подход с FilterIndex работать не будет - т.к. один плагин будет зарегистрирован в обоих диалогах (и поэтому нам нужно будет иметь два свойства-индекса, а не одно). Так что этот момент - ещё один вопрос для фиксации в документации. Сделать можно и так и этак - это как вы захотите. Но что бы вы ни выбрали - этот выбор, главное, надо закрепить в документации.

Скачать пример к статье.

В следующий раз - более сложные методы взаимодействия с плагинами, обработка ошибок.

В следующих статьях я уже не буду так подробно расписывать процесс разработки API. Подразумевается, что вы вами уже умеете это делать. Т.е. вы сначала всё продумаете, потом создадите заголовочники, потом напишете документацию.

Разработка системы плагинов в Delphi

2011-12-25T11:06:00.000+04:00

Эта статья - продолжение старой серии.

Напомню, что те статьи, несмотря на некоторый практический выхлоп в конце, всё же не очень-то освещали тему плагинов, а представляли собой копание во внутренностях работы DLL и пакетов Delphi. Было решено эту серию закончить - именно как серию о плагинах.

Ну, во-первых, причиной для новой статьи стали просьбы её продолжить/закончить. За три года они поступали регулярно. Во-вторых, я заметил, что многие люди ссылаются на эту статью как на руководство по разработке плагинов, хотя, как я уже сказал, оно таким не является. Сам я всегда ссылался на него со словами "вот, это не читай, но в первой части тут неплохая подборка ссылок по интересующей тебя теме".

В общем, все эти факторы в итоге перевесили мою лень и я решил написать нормальную статью про плагины.

Примечание: я был бы очень благодарен, если кто-нибудь со знанием Visual Studio (C++) просмотрел бы раздел 8 (и особенно - касательно генерации заголовочников для Visual Studio C++) на предмет моих ошибок.

Что у нас есть
Что хотим получить
Как пойдём
Основные понятия
Базовый набор правил и соглашений
Структура файлов и папок
Менеджер плагинов
API
- Управление заголовочниками
- Начала реализации функциональности

Что у нас есть

Напомню основные способы реализации систем плагинов:

Что хотим получить

Мы хотим разработать систему плагинов - т.е. набор правил, по которым сторонние разработчики (т.е. не авторы программы) могли бы писать функциональность, встраивающуюся в основную программу и как-бы являющуюся её частью. При этом хочется, чтобы плагины можно было бы писать на любом (нативном) языке программирования, а не только Delphi и C++ Builder.

При этом хочется, чтобы и работать было удобно, и чтобы у системы были бы мощные возможности. Как дополнительное пожелание - строить более-менее современную систему, а не по техникам 1995-го года.

Система должна по возможности допускать развитие со временем (добавление новых возможностей в будущем) с сохранением обратной совместимости (старые плагины работают в новой системе).

При этом предполагается, что плагины будут "тяжеловесные". Т.е. предполагающие существенный объём кода для реализации их функциональности. Ну, скажем, вроде как плагины звукового вывода в WinAmp, архиваторные, Lister-ые или FS-плагины в Total Commander или протокольные плагины в QIP.

Некоторые задачи более удачно ложатся на "легковесные плагины" - скрипты. К примеру, как макросы в MS Word. Вам нужно выбирать систему на скриптах, если ваши плагины должны много обращаться к интерфейсу (и, в частном случае, - внутренним объектам) программы, но при этом сами они относительно просты. Так, что их можно выразить на скриптовом языке. И в этом случае эта статья - не для вас (в этом случае могу ткнуть в направлении статьи про TMS Scripter Studio Pro в 6-м номере журнала Blaise Pascal Magazine).

В целом, в одном приложении вполне может быть реализовано две системы плагинов - для разных потребностей. К примеру, тот же MS Word (помимо макросов и VBA) поддерживает плагины в виде COM-объектов.

Как пойдём

Сразу замечу, что в этой статье я не буду говорить "почему". Я просто озвучу вариант, который выбрал я. Ответы на вопросы "почему" можно почерпнуть в старой серии статей.

Что это значит? Реализации одной и той же задачи может быть несколько. Все из них имеют плюсы и минусы. Я не могу описать все возможные варианты - у меня не хватит ни времени, ни терпения это сделать. Поэтому я буду описывать лишь один вариант. Этот вариант я выбрал, исходя из требований к системе плагинов, изложенных в предыдущем пункте.

По тексту я кратко могу пояснять причины выбора того или иного решения, но подробное объяснение и альтернативы будут за кадром.

Если вы не начинающий (а зачем вы это читаете?) - вы можете сделать такой выбор сами. Если же вы начинающий и озабочены тем, что не можете сделать выбор, вот мой совет - просто следуйте этой статье. Когда у вас накопится опыт, вы уже более чётко будете представлять себе, что вы хотите получить, какие есть варианты достижения этого, какие у них плюсы и минусы. Так что вы сможете сделать свой выбор. Потом, не сейчас.

Основные понятия

Плаги́н (от англ. plug-in) — независимо компилируемый программный модуль, динамически подключаемый к основной программе, предназначенный для расширения и/или использования её возможностей. Плагин - это маленькая программка, которая встраивается в основную (большую) программу и расширяет её возможности.

Основная программа при этом называется "ядро" (core).

Чаще всего основной программой является .exe файл, а плагины - это .dll файлы.

Ядро предоставляет сервисы, которые плагин может использовать. К ним относится предоставляемая плагину возможность зарегистрировать себя в ядре, а также протокол обмена данными с другими плагинами. Плагины являются зависимыми от сервисов, предоставляемых ядром и отдельно (сами по себе) не используются.

Протокол (также называемый API - Application Programming Interface) - набор правил, контракт, которому соглашаются следовать ядро и плагины, чтобы понять друг друга и успешно взаимодействовать. Все сервисы ядра могут предоставляться только в рамках этого соглашения.

Заголовочники, заголовочные файлы (headers) - набор исходных файлов, которые содержат объявления структур, использующихся в протоколе плагинов. Как правило, не содержат реализации. Заголовочные файлы предоставляются на нескольких языках - как правило, это язык, на котором написана программа (в нашем случае - Delphi), C++ (как стандарт) и некоторыми дополнительными (Basic и т.п.). Все эти файлы эквивалентны и просто представляют собой перевод из одного языка программирования на другой. Чем больше языков будет в комплекте - тем лучше. Если вы не предоставите заголовочные файлы для какого-то языка, то программисты на этом языке не смогут писать плагины для вашей программы, пока они сами не переведут файлы с предоставляемого языка (Delphi или C++) на их язык. Т.е. отсутствие заголовочников на каком-то языке - это не красный "стоп", но достаточное препятствие. В этом смысле очень удачно выглядит COM (где описание хранится в универсальном формате библиотеки типов - TLB). Вам не нужно ничего делать, кроме как распространять .tlb файл (который также может быть встроен в .dll). Если язык умеет работать с COM - он может импортировать информацию из TLB и создать заголовочник самостоятельно. TLB файл - это двоичный файл. Его создают и редактируют в каком-нибудь редакторе, либо он генерируется средой разработки. Его также можно "скомпилировать" из текстового описания - IDL файла (.idl или .ridl).

Документация - представляет собой словесное описание протокола плагинов. Она пишется разработчиком программы для разработчиков плагинов (т.е. она односторонняя). Конечно, вы можете вести документацию и для себя лично, но сейчас речь не про неё. Итак, в этой документации как минимум должно быть формальное описание API - перечисление всех функций, методов, интерфейсов и типов данных с объяснениями "как" и "зачем" (т.н. Reference). Дополнительно, документация может содержать неформальное описание процесса разработки плагинов (guide, how-to и т.п.). В простейших случаях документация пишется прямо в заголовочниках (комментариях), но чаще всего это файл (или файлы) в формате chm, html или pdf.

SDK (Software Development Kit) - набор из заголовочников и документации. SDK - это то, что необходимо стороннему разработчику для написания плагинов к вашей программе. SDK - это то, что вы должны создать и публично распространять для всех желающих писать плагины к вашей программе.

Базовый набор правил и соглашений

Итак, для системы плагинов я выбрал схему DLL + интерфейсы. Замечу, что мы не можем использовать пакеты по соображениям межязыковой совместимости, а COM мне не нравится отложенной выгрузкой :) Также замечу, что предлагаемая схема вполне будет способна работать с плагинами в виде пакетов, если вы захотите это сделать, но при этом не будет никаких плюшек пакетов (управление памятью, разделение классов), окромя бонуса с DllMain (как описано в оригинальной серии статей).

Правило номер два - в системе плагинов обязательно должны быть явные функции инициализации и финализации. Это значит, что каждая DLL должна экспортировать минимум 2 функции, которые будут вызываться непосредственно (первой) после загрузки плагина ядром и перед самой выгрузкой (последней).

Правило номер три - модель вызова любых функций и методов в системе плагинов должна быть safecall. Напомню, что safecall - это, на самом деле, stdcall с неявным HRESULT. Например, вот три примера эквивалентных объявлений (т.е. они написаны по-разному, но представляют собой одно и то же):

procedure DoSomething; safecall;
function  DoSomething: HRESULT; stdcall;

procedure DoSomethingElse(Param: Integer); safecall;
function  DoSomethingElse(Param: Integer): HRESULT; stdcall;

function DoSomethingMore: Integer; safecall;
function DoSomethingMore(out AResult: Integer): HRESULT; stdcall;

Правило номер четыре - обработка ошибок в стиле COM (safecall/HRESULT). Т.е. в Delphi это прозрачно будут исключения.

Правило номер пять - все строки должны иметь тип WideString.

Правило номер шесть - вы не должны использовать типы данных Delphi, потому что они не имеют аналога в других языках. Например, string, array of, TObject, TForm (и вообще любые объекты и уж тем более компоненты) и т.п. Что можно использовать - целочисленные типы (Integer, Cardinal, Int64, UInt64, NativeInt, NativeUInt, Byte, Word и т.п.; я бы не рекомендовал использовать Currency, если только он вам действительно нужен), вещественные (Single и Double; я бы рекомендовал избегать типов Extended и Comp, если только они действительно вам нужны и иначе никак), перечислимые и subrange-типы (с некоторыми оговорками), символьные типы (AnsiChar и WideChar, но не Char), строки (только в виде WideString), логический тип (BOOL, но не Boolean), интерфейсы (interface), в методах которых используются допустимые типы, записи (record) из вышеуказанных типов, а также указатели на них (в том числе указатели на массивы из вышеуказанных типов, но не динамические массивы).

Как узнать, какой тип можно использовать, а какой - нет? Относительно простое правило - если вы не видите тип в этом списке, и типа нет в модуле Windows (модуле Winapi.Windows, начиная с Delphi XE2), то этот тип использовать нельзя. Если же тип перечислен мною выше или находится в модуле Windows/Winapi.Windows - используйте его. Это достаточно грубое правило, но для начала - сойдёт.

Правило номер семь - как только вы опубликовали какой-то тип (интерфейс), вы не должны его изменять. Если вам нужно его расширить или изменить - вы вводите новый интерфейс (новую версию интерфейса), но не меняете старый.

Правило номер восемь - вы не используете разделяемый менеджер памяти (не подключаете модуля вроде ShareMem, SimpleShareMem и т.п.).

Правило номер девять - все интерфейсы API должны иметь GUID. Все интерфейсы вне API (используемые только ядром) могут не иметь GUID.

Структура папок и файлов

Следующий вопрос - какие файлы нам понадобятся, что нам нужно создать. Для начала заметим, что когда мы говорим о системе плагинов, то мы можем говорить с двух сторон: со стороны ядра и со стороны плагина. И ядро и плагин должны следовать контракту, который мы для них определим, но делать это они будут с разных сторон. Это означает, что нам потребуются:

Общие файлы - используются и ядром и плагинами
Файлы ядра (то, к чему не имеют доступа плагины)
Файлы плагинов (то, к чему не имеет доступа ядро)
Файлы вне системы плагинов (функциональность ядра и плагинов)

Поэтому, для начала, чтобы отделить п4 от пп1-3, давайте создадим новую папку (в любом месте), скажем - PluginAPI. В эту папку мы будем помещать всё то, что имеет отношение к системе плагинов, вне этой папки будем хранить всё остальное.

Далее, в этой папке создадим три подпапки: Headers (для общих файлов), Core (для файлов ядра) и Plugins (для файлов плагинов). Headers - это то, что вы должны распространять публично для всех желающих писать плагины для вашей программы (часть SDK, заголовочники). Core будет использоваться только вами (как разработчиком программы), а Plugins часто может оказаться пустой, но если это не так, то там лежат файлы, которые вы должны будете прикладывать к Headers, когда вы распространяете SDK. Это - дополнительная функциональность, обёртка вокруг заголовочников.

Далее, вы создаёте основную программу. Поскольку у меня программы нет, я возьму уже готовую - это демка RichEdit из комплекта поставки Delphi. Программа-пример представляет собой простой текстовый редактор. Файлы этой демки (remain.pas, remain.dfm и т.п.) относятся к пункту 4: файлы вне системы плагинов. Поэтому вы сохраняете основную программу в любом месте, а затем добавляете нужные файлы через Project/Add to project (либо прописываете пути поиска в проекте или IDE, но я не буду это показывать).

Какие файлы? Вроде у нас ещё ничего нет? Вот-вот. Так что давайте (наконец-то!) что-то попишем...

Менеджер плагинов

Откройте свою программу (в примере - скопированную демку RichEdit) и сделайте File/New unit. Сохраните этот модуль в папке PluginAPI\Core под именем PluginManager.pas и введите в него такую заготовку:

unit PluginManager;

interface

type
  IPluginManager = interface
  end;

function Plugins: IPluginManager;

implementation

uses
  SysUtils,
  Classes;

type
  TPluginManager = class(TInterfacedObject, IPluginManager)

  end;

//________________________________________________________________

var
  FPluginManager: IPluginManager;

function Plugins: IPluginManager;
begin
  Result := FPluginManager;
end;

initialization
  FPluginManager := TPluginManager.Create;
finalization
  FPluginManager := nil;
end.

Этот код объявляет и создаёт менеджер плагинов. Менеджер плагинов - это вспомогательный код в вашей программе, который служит для управления плагинами. Он выполняет всю черновую работу с плагинами, так что вам не нужно засорять код своей основной программы. Менеджер создаётся автоматически при старте программы и автоматически удаляется при выходе из программы.

Вы видите тут три части. Секция interface перечисляет то, с чем будет работать основная программа. Пока это глобальная функция Plugins для доступа к менеджеру и сам менеджер - интерфейс IPluginManager: пока пустой.

Вторая часть (до подчёркивания) содержит код менеджера плагинов - тоже пока пустой. Это черновая работа, которую мы скрываем "под капотом" модуля, чтобы она не засоряла код основной программы.

Часть три (после черты) представляет собой код инициализации и удаления менеджера плагинов. Поскольку мы работаем с ним через интерфейс, то для его удаления мы просто очищаем ссылку. Обратите внимание, что поскольку менеджер плагинов в данном случае является глобальным объектом, то мы используем для его хранения глобальную переменную. Однако заметьте, что при этом глобальная переменная объявлена последней и лежит практически в самом низу текста (новый код будет добавляться выше черты, но не ниже). Плюс, она закрыта от внешнего доступа секцией implementation. Т.е. она максимально изолирована от внешних воздействий.

Итак, что будет делать менеджер плагинов? Ну, наверное для начала плагины надо бы найти и загрузить. Как это обычно делают? Есть два способа:

Пользователь указывает в настройках программы, какие плагины нужно включать.
Плюсы:
- Пользователь может использовать плагин в любом месте.
- Пользователь может отключать плагин из интерфейса программы, не удаляя его.
Минусы:
- Пользователю нужно настраивать плагины вручную.
Программа загружает как плагины все файлы из предопределённой папки.
Плюсы:
- Пользователю ничего не надо делать.
Минусы:
- Чтобы удалить или добавить плагин, его нужно скопировать в папку или удалить из неё.
- Плагин нельзя "отключить", не удалив его.

В принципе, эти подходы можно комбинировать. Скажем, автозагружать плагины из папки, но при этом не загружать отключенные (исключения) и допускать загрузку по команде из другого места.

Итак, что должен уметь делать менеджер плагинов, чтобы реализовать какую-то из схем выше?

Загрузка одного плагина

Какую-бы схему мы ни реализовали бы - нам обязательно в любом случае потребуется функция загрузки одного плагина. Вот давайте с неё и начнём:

unit PluginManager;

interface

uses
  Windows;

type
  IPlugin = interface
  // protected
    function GetIndex: Integer;
    function GetHandle: HMODULE;
    function GetFileName: String;
  // public
    property Index: Integer read GetIndex;
    property Handle: HMODULE read GetHandle;
    property FileName: String read GetFileName;
  end;

  IPluginManager = interface
  // protected
    function GetItem(const AIndex: Integer): IPlugin;
    function GetCount: Integer;
  // public
    function LoadPlugin(const AFileName: String): IPlugin;
    procedure UnloadPlugin(const AIndex: Integer);

    property Items[const AIndex: Integer]: IPlugin read GetItem; default;
    property Count: Integer read GetCount;
  end;

function Plugins: IPluginManager;

implementation

uses
  SysUtils,
  Classes;

type
  TPluginManager = class(TInterfacedObject, IPluginManager)
  private
    FItems: array of IPlugin;
    FCount: Integer;
  protected
    function GetItem(const AIndex: Integer): IPlugin;
    function GetCount: Integer;
  public
    function LoadPlugin(const AFileName: String): IPlugin;
    procedure UnloadPlugin(const AIndex: Integer);
    function IndexOf(const APlugin: IPlugin): Integer;
  end;

  TPlugin = class(TInterfacedObject, IPlugin)
  private
    FManager: TPluginManager;
    FFileName: String;
    FHandle: HMODULE;
  protected
    function GetIndex: Integer;
    function GetHandle: HMODULE;
    function GetFileName: String;
  public
    constructor Create(const APluginManger: TPluginManager; const AFileName: String); virtual;
    destructor Destroy; override;
  end;

{ TPluginManager }

function TPluginManager.LoadPlugin(const AFileName: String): IPlugin;
begin
  // Загружаем плагин
  Result := TPlugin.Create(FManager, AFileName);

  // Заносим в список
  if Length(FItems) >= FCount then // "Capacity"
    SetLength(FItems, Length(FItems) + 64);
  FItems[FCount] := Result;
  Inc(FCount);
end;

procedure TPluginManager.UnloadPlugin(const AIndex: Integer);
var
  X: Integer;
begin
  // Выгрузить плагин
  FItems[AIndex] := nil;
  // Сдвинуть плагины в списке, чтобы закрыть "дырку"
  for X := AIndex to FCount - 1 do
    FItems[X] := FItems[X + 1];
  // Не забыть учесть последний
  FItems[FCount - 1] := nil;
  Dec(FCount);
end;

function TPluginManager.IndexOf(const APlugin: IPlugin): Integer;
var
  X: Integer;
begin
  Result := -1;
  for X := 0 to FCount - 1 do
    if FItems[X] = APlugin then
    begin
      Result := X;
      Break;
    end;
end;

function TPluginManager.GetCount: Integer;
begin
  Result := FCount;
end;

function TPluginManager.GetItem(const AIndex: Integer): IPlugin;
begin
  Result := FItems[AIndex];
end;

{ TPlugin }

constructor TPlugin.Create(const APluginManger: TPluginManager;
  const AFileName: String);
begin
  inherited Create;
  FManager := APluginManger;
  FFileName := AFileName;
  FHandle := SafeLoadLibrary(AFileName);
  Win32Check(FHandle <> 0);
end;

destructor TPlugin.Destroy;
begin
  if FHandle <> 0 then
  begin
    FreeLibrary(FHandle);
    FHandle := 0;
  end;
  inherited;
end;

function TPlugin.GetFileName: String;
begin
  Result := FFileName;
end;

function TPlugin.GetHandle: HMODULE;
begin
  Result := FHandle;
end;

function TPlugin.GetIndex: Integer;
begin
  Result := FManager.IndexOf(Self);
end;

//________________________________________________________________

...

end.

Ух, что-то тут много всего появилось. Давайте по порядку. Начнём с изменений в IPluginManager.

Собственно функция загрузки плагина - это LoadPlugin:

function LoadPlugin(const AFileName: String): IPlugin;

Как видите, она принимает имя файла плагина для загрузки. Очевидно, что она должна возвращать загруженный плагин. Нам надо его как-то представить - вот тут появляется новая сущность: "плагин". Он у нас представлен новым интерфейсом IPlugin.

Лирическое отступление. Сразу заметим такую вещь: сейчас мы говорим про внутреннюю кухню ядра, мы ещё не начали формировать API (напомню: исходный файл менеджера плагинов лежит в PluginAPI\Core, а не в PluginAPI\Headers). Именно поэтому тут совершенно нормально использовать string, соглашение вызова register и другие вещи, специфичные для Delphi: потому что их будет использовать только наша программа и никто иной.

Окей, возвращаясь к коду. Функция LoadPlugin устроена просто (если вы посмотрите на её реализацию в классе TPluginManager):

function TPluginManager.LoadPlugin(const AFileName: String): IPlugin;
begin
  // Загружаем плагин
  Result := TPlugin.Create(FManager, AFileName);

  // Заносим в список
  if Length(FItems) >= FCount then // "Capacity"
    SetLength(FItems, Length(FItems) + 64);
  FItems[FCount] := Result;
  Inc(FCount);
end;

Она создаёт наш плагин (в виде объекта TPlugin, реализующего интерфейс IPlugin) и регистрирует его в своём "списке всех плагинов" - FItems. Как вы видите, функция LoadPlugin на самом деле не выполняет непосредственно загрузку плагина, а делегирует (передаёт) эту работу классу-оболочке для плагина TPlugin. Это - правильно. Загрузка плагина - забота плагина и его класса. Управление плагинами - забота менеджера плагинов. Правильное разделение обязанностей, короче говоря.

Раз уж у нас появился "список плагинов", то неплохо бы его выставить наружу - так в IPluginManager появляются свойства Items и Count:

  IPluginManager = interface
  // protected
    function GetItem(const AIndex: Integer): IPlugin;
    function GetCount: Integer;
  // public
    ...
    property Items[const AIndex: Integer]: IPlugin read GetItem; default;
    property Count: Integer read GetCount;
  end;

Они дают ядру доступ к списку плагинов, позволяя их перебрать.

Ну и если плагин загружен, то надо ведь и обратное действие уметь выполнять: выгрузку плагинов. Вот у нас появляется ещё один метод: UnloadPlugin.

procedure UnloadPlugin(const AIndex: Integer);

Метод принимает номер плагина для его выгрузки. Из его реализации (в классе TPluginManager):

procedure TPluginManager.UnloadPlugin(const AIndex: Integer);
var
  X: Integer;
begin
  // Выгрузить плагин
  FItems[AIndex] := nil;
  // Сдвинуть плагины в списке, чтобы закрыть "дырку"
  for X := AIndex to FCount - 1 do
    FItems[X] := FItems[X + 1];
  // Не забыть учесть последний
  FItems[FCount - 1] := nil;
  Dec(FCount);
end;

видно, что он просто удаляет плагин из списка, уничтожая его.

Пока мы ещё говорим про класс менеджера плагинов, заметим такую вещь: мы работаем с интерфейсами и для FItems у нас используется динамический массив. Это значит, что все типы данных являются управляемыми и нам не нужно их освобождать руками. Т.е. если ядро вызовет три раза LoadPlugin для загрузки трёх плагинов, а потом просто выйдет, то у нас не будет никакой утечки памяти. Менеджер плагинов начнёт удаляться в finalization (при условии, что ссылку на него никто больше не держит), при этом автоматически очистится FItems (как авто-управляемый динамический массив), а все его элементы будут автоматически освобождены (как автоуправляемые интерфейсы) - опять же при условии, что на них больше нет ссылок. В этот момент и произойдёт выгрузка каждого плагина.

Итак, с IPluginManager и TPluginManager мы закончили, давайте посмотрим теперь на IPlugin/TPlugin.

Тут пока совсем всё просто: наружу интерфейс выставляет несколько свойств, которые могут быть интересны ядру: индекс плагина, имя файла и описатель загруженного файла.

  IPlugin = interface
  // protected
    function GetIndex: Integer;
    function GetHandle: HMODULE;
    function GetFileName: String;
  // public
    property Index: Integer read GetIndex;
    property Handle: HMODULE read GetHandle;
    property FileName: String read GetFileName;
  end;

Реализация методов в классе TPlugin тривиальна. Единственный момент - обратите внимание на реализацию свойства Index.

function TPlugin.GetIndex: Integer;
begin
  Result := FManager.IndexOf(Self);
end;

В данном случае оно реализовано через поиск (см. TPluginManager.IndexOf).

function TPluginManager.IndexOf(const APlugin: IPlugin): Integer;
var
  X: Integer;
begin
  Result := -1;
  for X := 0 to FCount - 1 do
    if FItems[X] = APlugin then
    begin
      Result := X;
      Break;
    end;
end;

Можно было бы сделать иначе: хранить индекс плагина в поле класса TPlugin. Оба решения имеют как плюсы, так и минусы, но в целом разницы нет никакой (у вас будет загружено более 1000 плагинов? Навряд ли).

Более интересно выглядят (скрытые) конструктор и деструктор плагина. Помимо тривиальностей по инициализации и заполнению свойств плагина, они выполняют собственно работу, ради которой всё и затевалось: загрузку и выгрузку DLL.

constructor TPlugin.Create(const APluginManger: TPluginManager;
  const AFileName: String);
begin
  inherited Create;
  FManager := APluginManger;
  FFileName := AFileName;
  FHandle := SafeLoadLibrary(AFileName); // работа: загрузка
  Win32Check(FHandle <> 0);
end;

destructor TPlugin.Destroy;
begin
  if FHandle <> 0 then // работа: выгрузка
  begin
    FreeLibrary(FHandle);
    FHandle := 0;
  end;
  inherited;
end;

Уже в этот момент этот код можно потестировать. К примеру, если вы бросите на форму основной программы TButton, TEdit и TListbox, то вы можете написать такой тестовый код:

type
  TMainForm = class(TForm)
    ...
  private
    ...
    procedure UpdatePluginsList;
  end;

...

implementation

uses
  REAbout, RichEdit, ShellAPI, ReInit,
  PluginManager; // <- новый модуль

...

procedure TMainForm.Button1Click(Sender: TObject);
begin
  Plugins.LoadPlugin(Edit1.Text);
  UpdatePluginsList;
end;

procedure TMainForm.UpdatePluginsList;
var
  X: Integer;
begin
  ListBox1.Items.BeginUpdate;
  try
    ListBox1.Items.Clear;
    for X := 0 to Plugins.Count - 1 do
      ListBox1.Items.Add(IntToStr(Plugins[X].Index) + ': ' + Plugins[X].FileName);
  finally
    ListBox1.Items.EndUpdate;
  end;
end;

...

end.

Запустите программу, вы можете ввести в Edit имя файла любой DLL и нажать на кнопку для загрузки её как плагина. При этом она тут же появится в списке загруженных плагинов.

Конечно, сейчас это может показаться несколько странным: как это так получается, что любая DLL может быть загружена как плагин? И что вообще делает этот плагин? Собственно, ничего странного нет: ведь мы пока не написали ни одной строчки API, у нас нет никакого контракта для плагинов, пока мы писали лишь код поддержки. Именно поэтому для плагина (пока!) подходит любая DLL и она просто ничего не делает.

По этой же причине, уже написанный код - универсален и может быть использован как база для любой новой системы плагинов.

Загрузка папки с плагинами

Следующая задача - загрузить целую папку с плагинами. Раз у нас уже есть функция загрузки одного плагина, то теперь мы можем вызвать её в цикле по всем плагинам в папке (пусть даже пока функция загрузки просто грузит DLL, а сами плагины пока что ничего не делают - не беда).

Я не буду приводить весь код целиком, а приведу лишь добавленный и изменённый код. Код в многоточиях оставлен без изменений.

interface

uses
  Windows,
  SysUtils,
  Classes;

type
  EPluginManagerError = class(Exception);
    EPluginLoadError = class(EPluginManagerError);
      EPluginsLoadError = class(EPluginLoadError)
      private
        FItems: TStrings;
      public
        constructor Create(const AText: String; const AFailedPlugins: TStrings);
        destructor Destroy; override;
        property FailedPluginFileNames: TStrings read FItems;
      end;

...

  IPluginManager = interface
    ...  
    procedure LoadPlugins(const AFolder: String; const AFileExt: String = '');
    ...
  end;

...

implementation

resourcestring
  rsPluginsLoadError = 'One or more plugins has failed to load:' + sLineBreak + '%s';

type
  TPluginManager = class(TInterfacedObject, IPluginManager)
    ...  
    procedure LoadPlugins(const AFolder, AFileExt: String);
    ...
  end;

...

procedure TPluginManager.LoadPlugins(const AFolder, AFileExt: String);

  function PluginOK(const APluginName, AFileExt: String): Boolean;
  begin
    Result := (AFileExt = '');
    if Result then
      Exit;
    Result := SameFileName(ExtractFileExt(APluginName), AFileExt);
  end;

var
  Path: String;
  SR: TSearchRec;
  Failures: TStringList;
  FailedPlugins: TStringList;
begin
  Path := IncludeTrailingPathDelimiter(AFolder);

  Failures := TStringList.Create;
  FailedPlugins := TStringList.Create;
  try
    if FindFirst(Path + '*.*', faNormal, SR) = 0 then
    try
      repeat
        if ((SR.Attr and faDirectory) = 0) and
           PluginOK(SR.Name, AFileExt) then
        try
          LoadPlugin(Path + SR.Name);
        except
          on E: Exception do
          begin
            FailedPlugins.Add(SR.Name);
            Failures.Add(Format('%s: %s', [SR.Name, E.Message]));
          end;
        end;
      until FindNext(SR) <> 0;
    finally
      FindClose(SR);
    end;

    if Failures.Count > 0 then
      raise EPluginsLoadError.Create(Format(rsPluginsLoadError, [Failures.Text]), FailedPlugins);
  finally
    FreeAndNil(FailedPlugins);
    FreeAndNil(Failures);
  end;
end;

...

function TPluginManager.LoadPlugin(const AFileName: String): IPlugin;
begin
  // Загружаем плагин
  try
    Result := TPlugin.Create(FManager, AFileName);
  except
    on E: Exception do
      raise EPluginLoadError.Create(Format('[%s] %s', [E.ClassName, E.Message]));
  end;

  ...
end;

...

{ EPluginsLoadError }

constructor EPluginsLoadError.Create(const AText: String;
  const AFailedPlugins: TStrings);
begin
  inherited Create(AText);
  FItems := TStringList.Create;
  FItems.Assign(AFailedPlugins);
end;

destructor EPluginsLoadError.Destroy;
begin
  FreeAndNil(FItems);
  inherited;
end;

//________________________________________________________________

Опять у нас получилось больше кода, чем изначально планировалось. И вот почему.

Как видите, основной новый метод тут - LoadPlugins. Он принимает имя папки и необязательное расширение файлов. Реализация метода ищет в указанной папке все файлы и загружает те из них, которые подходят под указанное расширение. Если расширение не указывать, то будут загружены вообще все файлы.

К примеру:

procedure TMainForm.Button2Click(Sender: TObject);
begin
  try
    Plugins.LoadPlugins('C:\Windows', '.dll'); // загрузить все DLL из папки Windows
  finally
    UpdatePluginsList;
  end;
end;

или:

procedure TMainForm.Button2Click(Sender: TObject);
begin
  try
    Plugins.LoadPlugins(Edit1.Text); // загрузить вообще все файлы из указанной папки
  finally
    UpdatePluginsList;
  end;
end;

В реализации метода LoadPlugins нет ничего сложного, за исключением одного момента: обработка ошибок. Предположим, один из плагинов не смог загрузится. Что тогда делать? Есть два варианта: первый - остановиться и сообщить об ошибке. Это самый простой вариант и он мне не нравится. Зато можно было бы ничего больше не писать. Вариант два - продолжить загрузку плагинов. Именно этот вариант я и показал. Тут возникает вопрос, что делать с ошибкой загрузки плагина и как о ней сообщить. Ведь если мы грузим целую папку с плагинами, то отказать в загрузке может не один плагин, а много.

Ответ заключается в том, что мы запоминаем плагины, которые не удалось загрузить. Но при этом продолжаем их загружать. В самом конце операции загрузки мы возбуждаем одну-единственную ошибку (одну - даже если несколько плагинов отказало), в которой суммируем информацию.

Тут возникает два момента: во-первых, раз уж мы возбуждаем свою ошибку, то нам надобен для этого класс. Использовать Exception я вам категорически запрещаю. Поэтому мы вводим свои классы ошибок:

type
  EPluginManagerError = class(Exception); // для всех ошибок менеджера плагинов
    EPluginLoadError = class(EPluginManagerError); // для ошибок загрузки плагинов
      EPluginsLoadError = class(EPluginLoadError); // для ошибок загрузки плагинов в папке

Кроме того, для последней ситуации кроме сообщения нам требуется хранить дополнительную информацию: список плагинов, которые отказались грузится. Зачем это нужно? Ну, скажем, ядро может отключить сбойнувшие плагины, чтобы не грузить их во второй раз в будущем при следующей загрузке. Плагин сбойнул? Отключили. Если пользователь исправит ошибку, препятствующую загрузке плагина - он включит плагин обратно.

Итак, для этого к исключению мы пристыковываем список файловых имён:

EPluginsLoadError = class(EPluginLoadError)
private
  FItems: TStrings;
public
  constructor Create(const AText: String; const AFailedPlugins: TStrings);
  destructor Destroy; override;
  property FailedPluginFileNames: TStrings read FItems;
end;

А метод LoadPlugins теперь может собирать информацию о сбойнувших плагинах:

try
  LoadPlugin(Path + SR.Name);
except
  on E: Exception do
  begin
    // Запомнили имя файла сбойнувшего плагина
    FailedPlugins.Add(SR.Name); 
    // И вписали возникшую проблему в общий список ошибок
    Failures.Add(Format('%s: %s', [SR.Name, E.Message])); 
  end;
end;

и возбуждать единую ошибку в конце работы:

if Failures.Count > 0 then // есть хотя бы один сбойнувший плагин?
  raise EPluginsLoadError.Create(Format(rsPluginsLoadError, [Failures.Text]), FailedPlugins);

Ну и раз уж мы определили свои типы ошибок, неплохо бы их соблюдать. Поэтому изменяем метод LoadPlugin, чтобы при исключении он возбуждал бы именно наш тип ошибки:

function TPluginManager.LoadPlugin(const AFileName: String): IPlugin;
begin
  // Загружаем плагин
  try
    Result := TPlugin.Create(FManager, AFileName);
  except
    on E: Exception do
      raise EPluginLoadError.Create(Format('[%s] %s', [E.ClassName, E.Message]));
  end;

  ...
end;

Ну, вроде и всё с этим. Как обычно, вы можете проверить код в своём приложении - пусть оно грузит содержимое подпапки Plugins. Пусть даже сейчас это ничего не будет делать.

Отключение плагинов

Итак, у нас есть функция загрузки одного плагина по команде пользователя, есть автозагрузка плагинов из папки, а теперь осталось лишь сделать отключение загрузки плагина без его удаления.

К этой задаче можно подступиться по разному. Я предлагаю такое решение: завести "чёрный список" плагинов. Любой плагин можно добавить в этот список. Любой плагин можно удалить из списка. Функция LoadPlugin (а следовательно и функция LoadPlugins) не станет грузить плагин, если он находится в чёрном списке. Соотвественно, чтобы отключить плагин - его надо занести в чёрный список (рассматривайте его как список отключенных плагинов), а чтобы включить - удалить из этого списка.

Плагины можно идентифицировать по разному, но поскольку речь идёт о стадии загрузки, то наиболее естественно будет идентификация по полному имени файла - то, что передаётся в функцию LoadPlugin.

Итого получаем (и снова, я привожу лишь изменения, а не весь код):

type
  ...
  IPluginManager = interface
    ...
    procedure Ban(const AFileName: String);
    procedure Unban(const AFileName: String);

    procedure SaveSettings(const ARegPath: String);
    procedure LoadSettings(const ARegPath: String);
    ...
  end;

...

implementation

...

type
  TPluginManager = class(TInterfacedObject, IPluginManager)
  private
    ...
    FBanned: TStringList;
  protected
    ...
    function CanLoad(const AFileName: String): Boolean;
  public
    constructor Create;
    destructor Destroy; override;
    ...
    procedure Ban(const AFileName: String);
    procedure Unban(const AFileName: String);
    procedure SaveSettings(const ARegPath: String);
    procedure LoadSettings(const ARegPath: String);
  end;

  ...

{ TPluginManager }

constructor TPluginManager.Create;
begin
  inherited Create;
  FBanned := TStringList.Create;
end;

destructor TPluginManager.Destroy;
begin
  FreeAndNil(FBanned);
  inherited;
end;

function TPluginManager.LoadPlugin(const AFileName: String): IPlugin;
begin
  if not CanLoad(AFileName) then
  begin
    Result := nil;
    Exit;
  end;

  // Загружаем плагин
  ...
end;

...

procedure TPluginManager.Ban(const AFileName: String);
begin
  Unban(AFileName);
  FBanned.Add(AFileName);
end;

procedure TPluginManager.Unban(const AFileName: String);
var
  X: Integer;
begin
  for X := 0 to FBanned.Count - 1 do
    if SameFileName(FBanned[X], AFileName) then
    begin
      FBanned.Delete(X);
      Break;
    end;
end;

function TPluginManager.CanLoad(const AFileName: String): Boolean;
var
  X: Integer;
begin
  // Не грузить отключенные
  for X := 0 to FBanned.Count - 1 do
    if SameFileName(FBanned[X], AFileName) then
    begin
      Result := False;
      Exit;
    end;

  // Не грузить уже загруженные
  for X := 0 to FCount - 1 do
    if SameFileName(FItems[X].FileName, AFileName) then
    begin
      Result := False;
      Exit;
    end;

  Result := True;
end;

const
  SRegDisabledPlugins = 'Disabled plugins';
  SRegPluginX         = 'Plugin%d';

procedure TPluginManager.SaveSettings(const ARegPath: String);
var
  Reg: TRegIniFile;
  Path: String;
  X: Integer;
begin
  Reg := TRegIniFile.Create(ARegPath, KEY_ALL_ACCESS);
  try
    // Удаляем старые
    Reg.EraseSection(SRegDisabledPlugins);
    Path := ARegPath + '\' + SRegDisabledPlugins;
    if not Reg.OpenKey(Path, True) then
      Exit;

    // Сохраняем новые
    for X := 0 to FBanned.Count - 1 do
      Reg.WriteString(Path, Format(SRegPluginX, [X]), FBanned[X]);
  finally
    FreeAndNil(Reg);
  end;
end;

procedure TPluginManager.LoadSettings(const ARegPath: String);
var
  Reg: TRegIniFile;
  Path: String;
  X: Integer;
begin
  Reg := TRegIniFile.Create(ARegPath, KEY_READ);
  try
    FBanned.BeginUpdate;
    try
      FBanned.Clear;

      // Читаем
      Path := ARegPath + '\' + SRegDisabledPlugins;
      if not Reg.OpenKey(Path, True) then
        Exit;
      Reg.ReadSectionValues(Path, FBanned);

      // Убираем "Plugin5=" из строк
      for X := 0 to FBanned.Count - 1 do
        FBanned[X] := FBanned.ValueFromIndex[X];
    finally
      FBanned.EndUpdate;
    end;
  finally
    FreeAndNil(Reg);
  end;
end;

Тут тоже ничего сложного: чёрный список плагинов хранится в FBanned, куда плагин можно добавить или из которого удалить через функции Ban и Unban соответственно. Функция CanLoad используется для определения статуса плагина: нужно его грузить или нет. Помимо собственно чёрного списка, функция дополнительно проверяет уже загруженные плагины, блокируя их повторную загрузку.

Вспомогательные функции Save- и LoadSettings используются для сохранения и загрузки списка заблокированных плагинов в реестр, следуя правилам хорошего тона. Таким образом, тестовый код может выглядеть так:

procedure TMainForm.Button3Click(Sender: TObject);
begin
  Plugins.Ban(Edit1.Text);
end;

procedure TMainForm.Button4Click(Sender: TObject);
begin
  Plugins.Unban(Edit1.Text);
end;

procedure TMainForm.FormCreate(Sender: TObject);
begin
  Plugins.LoadSettings('\SOFTWARE\MyCompany\MyProduct');
  ...
end;

procedure TMainForm.FormDestroy(Sender: TObject);
begin
  Plugins.SaveSettings('\SOFTWARE\MyCompany\MyProduct');
end;

Результат работы функции SaveSettings в реестре выглядит так:

Разумеется, ничто не мешает вам реализовать функции сохранения/загрузки как-то иначе, или вовсе вынести их за пределы менеджера плагинов: пусть конфигурацию сохраняет и восстанавливает код основной программы.

Итак, мы написали менеджер плагинов в минимальном варианте. Вы можете расширять его функциями-обёртками для вашего удобства (например, ввести функцию, возвращающую загруженный плагин по имени файла), но это уже будет дополнительные удобства. Сейчас же самое время перейти к следующему шагу - собственно плагинам.

Скачать исходный код к этому моменту можно тут.

API

Теперь, когда у нас готова основа архитектуры плагинов со стороны ядра, можно начать прорабатывать контракт плагинов: API. Начнём с их инициализации. Как уже говорилось, у DLL должно быть минимум две функции: инициализации и финализации, которые будут вызываться первыми и последними. Вот давайте их сейчас и напишем. Откройте вашу программу и сделайте File/New unit. Сохраните новый модуль в папке PluginAPI\Headers под именем PluginAPI.pas:

unit PluginAPI;

interface

type
  TInitPluginFunc = function(const ACore: IUnknown): IUnknown; safecall;
  TDonePluginFunc = procedure; safecall;

const
  SPluginInitFuncName = '87D4EDFB420343F2976EB3CF4DB7C224';
  SPluginDoneFuncName = SPluginInitFuncName + '_done';
  SPluginExt          = '.MyAppPlugin';

implementation

end.

Здесь мы определяем прототипы двух функций (Init и Done). Обе они имеют соглашение вызова safecall, а функция инициализации к тому же принимает параметры от ядра и возвращает плагин (т.е. самого себя). Пока у нас нет функциональности, поэтому я вписал самый базовый интерфейс, который только может быть. Заметьте, что мы сейчас уже говорим про API, поэтому должны придерживаться упомянутых в начале статье правил - в частности, касаемо соглашения вызова и типов данных.

Также в модуле определены имена, которые должны иметь функции инициализации и финализации. Имена выбраны как случайные - это сделано специально, чтобы в произвольной DLL таких имён точно бы не оказалось. Таким образом, если загружать произвольную DLL как плагин, то эта операция будет неудачной, потому что в произвольно взятой DLL (а не специально разработанном плагине) уж точно нет функции с именем '87D4EDFB420343F2976EB3CF4DB7C224'. Для получения такого имени я нажал в редакторе кода Delphi комбинацию Ctrl + Shift + G и получил:

['{87D4EDFB-4203-43F2-976E-B3CF4DB7C224}']

После чего я удалил [], {} и -, оставив только

'87D4EDFB420343F2976EB3CF4DB7C224'

И таким образом я получил имя, которое гарантировано уникально.

Если вы будете использовать мой код в своих проектах, то вы должны для каждого своего проекта сгенерировать свою константу так же, как это сделал я. Это необходимо, чтобы плагины от одной программы нельзя было бы загрузить в другой.

Наконец, тут определена константа для расширений плагинов. К примеру, загрузка плагинов (возвращаясь к примеру с менеджером плагинов) тогда будет выглядеть так:

Plugins.LoadFolder(ExtractFilePath(ParamStr(0))) + 'Plugins', SPluginExt);

Т.е. мы говорим, что плагин для нашей программы представляет собой переименованную в .MyAppPlugin-файл обыкновенную DLL, которая экспортирует функции 87D4EDFB420343F2976EB3CF4DB7C224 и 87D4EDFB420343F2976EB3CF4DB7C224_done с прототипами, указанными выше, и расположенная в подпапке Plugins основной программы.

Возьмите на заметку - это слова для вашей (будущей) документации к плагинам.

В любом случае, давайте во-первых научим работать с этим наш менеджер плагинов, а потом напишем пустой плагин (ибо после внесения изменений в программу уже нельзя будет загрузить произвольную DLL):

unit PluginManager;

...

implementation

uses
  Registry,
  PluginAPI;

...

type
  TPlugin = class(TInterfacedObject, IPlugin)
  private
    ...
    FInit: TInitPluginFunc;
    FDone: TDonePluginFunc;
    FPlugin: IInterface;
  protected
    ...  
  end;
  
...

{ TPlugin }

constructor TPlugin.Create(const APluginManger: TPluginManager;
  const AFileName: String);
begin
  ...
  FDone := GetProcAddress(FHandle, SPluginDoneFuncName);
  FInit := GetProcAddress(FHandle, SPluginInitFuncName);
  Win32Check(Assigned(FInit));
  FPlugin := FInit(FManager);
end;

destructor TPlugin.Destroy;
begin
  FPlugin := nil;
  if Assigned(FDone) then
    FDone;
  ...
end;

...

end.

Мне кажется, тут всё очевидно. Хочу только обратить внимание, что Init-функцию мы подразумеваем обязательной, а Done функцию - опциональной (т.е. она может отсутствовать, если она не нужна плагину).

Теперь давайте создадим плагин. Для этого сделайте File/New/Delphi Projects/Dynamic-Link Library и сохраните куда-нибудь проект (вне папки PluginAPI). Затем сделайте File/Add to project и укажите файл PluginAPI.pas. После чего напишите минимальный код:

library Plugin1;

uses
  PluginAPI in 'PluginAPI\Headers\PluginAPI.pas';

{$R *.res}

function Init(const ACore: IInterface): IInterface; safecall;
begin
  Result := nil;
end;

procedure Done; safecall;
begin
  // ничего не делает
end;

exports
  Init name SPluginInitFuncName,
  Done name SPluginDoneFuncName;

end.

Мы просто вставили пустые функции инициализации и финализации и экспортировали их.

Пока мы ничего сделать не можем, потому что ещё не определили функциональность. Но в этот момент мы можем проверить, как плагин и приложение работают вместе. Попробуйте как и ранее загрузить произвольную DLL - это не сработает. А теперь попробуйте загрузить наш плагин - операция пройдёт успешно.

Управление заголовочниками

Начнём понемногу строить функциональность. Давайте начнём с самого простого - добавим возможность ядру узнать версию плагина, а плагину - версию ядра.

Очевидно, что для этого нам нужно объявить два интерфейса: один для ядра и один для плагина. Или один интерфейс для обоих сразу. В любом случае, интерфейс будет иметь метод (и свойство) для получения версии.

Тут сразу же я хотел бы рассмотреть вот какой момент. Предположим, сейчас мы напишем (слово "предположим" означает что это писать не надо):

unit PluginAPI;

interface

...

type
  IPluginInfo = interface
  ['{F96EFCD5-17F6-4C17-956C-219F23C51AF9}']
  // private
    function GetID: TGUID; safecall;
    function GetName: WideString; safecall;
    function GetVersion: WideString; safecall;
  // public
    property ID: TGUID read GetID;
    property Name: WideString read GetName;
    property Version: WideString read GetVersion;
  end;

  ICoreInfo = interface
  ['{525797CF-89EB-4226-8BFE-4E3DD2123E13}']
  // private
    function GetVersion: Integer; safecall;
  // public
    property Version: Integer read GetVersion;
  end;

implementation

end.

Мы можем использовать эти объявления и включить заголовочный файл PluginAPI.pas в SDK (вместе с его описанием в документации). Хорошо, но что будут делать программисты, работающие на других языках? Один из вариантов - перевести все .pas файлы на C++. К примеру, наш файл PluginAPI.pas, будучи переведённым на C++, станет выглядеть как-то так:

namespace Pluginapi
{
//-- type declarations -------------------------------------------------------
typedef HRESULT __stdcall (*TInitPluginFunc)(IUnknown *ACore, IUnknown **Result);
typedef HRESULT __stdcall (*TDonePluginFunc)(void);

MIDL_INTERFACE("F96EFCD5-17F6-4C17-956C-219F23C51AF9")
IPluginInfo : public IUnknown
{
public:
 virtual HRESULT __stdcall GetID(GUID *Result) = 0;
 virtual HRESULT __stdcall GetName(BSTR *Result) = 0;
 virtual HRESULT __stdcall GetVersion(BSTR *Result) = 0;
};

MIDL_INTERFACE("525797CF-89EB-4226-8BFE-4E3DD2123E13")
ICoreInfo : public IUnknown
{
public:
 virtual HRESULT __stdcall GetVersion(int *Result) = 0;
};

//-- var, const, procedure ---------------------------------------------------
#define SPluginInitFuncName L"87D4EDFB420343F2976EB3CF4DB7C224"
#define SPluginDoneFuncName L"87D4EDFB420343F2976EB3CF4DB7C224_done"
#define SPluginExt L".MyAppPlugin"

} /* namespace Pluginapi */

Примечание: чёрт, я мало что понимаю в C++, так что с переводом я мог наврать. Буду благодарен, если мне ткнут носом в правильный перевод.

Как видите, текст дословно дублирует паскалевский код, но на другом языке (C++). Т.е. это просто копия.

Суть такого телодвижения в том, что C++ - это де-факто стандарт. Если кто-то не программирует на Delphi, то он программирует либо на C++ (и тогда он может воспользоваться указанным заголовочником), либо программирует на другом языке. В последнем случае ему придётся переводить заголовочники (с Delphi или C++ на свой язык) самостоятельно.

В любом случае, если вы в основном работаете на Delphi и слабо знакомы с другими языками, либо же вы хотите как-то автоматизировать работу (перевод заголовочников - не самая приятная работа, к тому же тут легко ошибиться: забыть перевести внесённые изменения), то вам захочется подыскать другой способ. Хотя, повторюсь, вы можете просто писать .pas файлы и переводить их на другие языки - это отлично будет работать.

Но сейчас я предлагаю воспользоваться ещё одним заимствованием из COM: библиотекой типов.

Библиотеки типов

Я кратко уже описал смысл выше: библиотека типов - это универсальное хранилище информации о сборке. Она хранится в двоичном формате (TLB) либо как отдельный файл (.tlb), либо как ресурс внутри .dll. С библиотеками типов умеют работать почти все современные компиляторы под Windows. Если кто-то умеет работать с COM, то он умеет работать и с библиотекой типов.

Самое важное для нас тут то, что библиотека типов может быть импортирована сторонней средой разработки, и при этом среда разработки сама (и автоматически) сгенерирует все необходимые исходные файлы. К примеру, если импортировать TLB в Delphi - Delphi сама создаст .pas заголовочник. Если импортировать TLB в Visual Studio C++ - она сама создаст .hpp файлы. Аналогичное справедливо и для других сред разработки (импортировать TLB можно даже в PHP!).

Короче говоря, с точки зрения хранимых сведений, библиотека является более продвинутым аналогом заголовочных файлов - поскольку хранит в себе гораздо больше полезной информации, компактнее и быстрее (не нужно делать парсинг заголовочных файлов) и, главное, может использоваться в любой среде разработки и любом языке программирования, которые поддерживает COM, а не только в Delphi.

Давайте создадим описание наших интерфейсов в виде библиотеки типов. Я буду описывать процесс, используя Delphi XE2, но это же должно быть верно и для более старых версий Delphi, включая Delphi 7 - правда, с некоторыми оговорками. Итак, выберите File/New/ActiveX/Type Library. Появится редактор библиотеки типов:

Редактор в Delphi 7

Редактор в Delphi XE2

Сохраните этот файл с именем PluginAPI в папке PluginAPI\Headers. В Delphi XE2 это будет файл PluginAPI.ridl, а в Delphi 7 - PluginAPI.tlb. .ridl-файл - это текстовый формат, .tlb - двоичный.

Тут есть один не совсем очевидный момент: в Delphi XE2 на экране вы видите 2 кнопки сохранения: во-первых, это стандартная кнопка в панели инструментов, а, во-вторых, это кнопка сохранения в редакторе библиотеки типов (она видна на снимке экрана выше - это самая правая кнопка в панели инструментов редактора библиотеки типов). Так вот, чтобы сохранить изменения в библиотеки типов, нужно нажать на стандартную кнопку сохранения, а не на кнопку сохранения в редакторе библиотеки типов. Это ещё более неочевидно, потому что изменения в библиотеки типов не приводят к немедленному включению стандартной кнопки сохранения Save all. Чтобы она включилась, нужно переключить вкладки - уйти с редактора библиотеки типов на, скажем, главный модуль программы или страницу Welcome и вернуться обратно. После этого кнопка сохранения будет активной.

Если же вы щёлкните на кнопке сохранения в редакторе библиотеки типов, то это будет не сохранение, а экспорт в .tlb-файл (напомню, что Delphi XE2 хранит библиотеку типов в текстовом формате в .ridl файле). В Delphi 7 это немного попроще, потому что кнопка экспорта так и называется - экспорт. И выглядит она по другому. Соответственно, в Delphi 7 эта кнопка экспортирует двоичный файл в текстовый.

В общем, Delphi 7 и Delphi XE2 ведут себя с точностью до наоборот. Нам это, впрочем никак не мешает, поскольку одно в другое преобразовать не проблема.

В любом случае, при создании библиотеки типов ей автоматически был присвоен уникальный GUID и установлена версия 1.0. А после сохранения её в файл она стала иметь имя "PluginAPI". На первой вкладке вам ничего больше менять не нужно. Теперь переключитесь на вкладку "Uses" и сбросьте галочку с "Borland standard VCL type library", оставив только "OLE Automation". Это отвяжет библиотеку типов от Delphi (при этом среда покажет предупреждение, что теперь с этой библиотекой типов не будут работать некоторые Delphi-вые фишки - соглашайтесь).

Теперь создадим в библиотеке типов наши интерфейсы IPluginInfo и ICoreInfo. Для этого щёлкните по первой (красной) кнопке в панели инструментов редактора библиотеки типов, либо же щёлкните по ней правой кнопкой мыши и выберите New\Interface. Это создаст новый интерфейс с автоматически сгенерированным GUID. Установите ему имя в "IPluginInfo", версию - в 1.0, а предка - в IUnknown:

На вкладке "Flags" сбросьте опции "Dual" и "OLE Automation". Это отключит дополнительные возможности COM, объявив интерфейс в чистом виде.

Далее щёлкните правой кнопкой по интерфейсу в дереве и выберите New\Property - это создаст два метода-акцесора Get и Set. Поскольку свойства у нас только для чтения, то удалите метод Set, оставив только Get (Get - первый, Set - второй; ещё их можно опознать по свойству Invoke kind: Put - это Set, ну а Get - это Get). Установите имя в ID, а тип данных - в GUID. Больше ничего менять не нужно.

Аналогично создайте свойства Name и Version, имеющие тип BSTR, а также интерфейс ICoreInfo со свойством Version, имеющим тип long:

Готово.

Тут надо сделать замечание по поводу типов данных. Типы данных указываются в "стиле C++", а не Delphi. К примеру, GUID вместо TGUID, BSTR вместо WideString, int вместо Integer, long вместо LongInt, * вместо ^ (указатель) и так далее. Список соответствия можно посмотреть в этой статье. Кроме того, поскольку интерфейсы в C++ являются просто абстрактными классами, а экземпляры классов в C++ не являются по умолчанию указателями (как в Delphi), то с именами интерфейсов необходимо явно указывать указатель, например:

IUnknown*

Когда вы закончите формировать библиотеку типов, сохраните её. Также сделайте экспорт в альтернативный формат (в Delphi 7 - в текстовый, в Delphi XE2 - в двоичный). В текстовом виде наша библиотека сейчас выглядит примерно так:

[
  uuid(F156F71A-758A-40E2-A34E-50187B8ED7B9),
  version(1.0)

]
library PluginAPI
{

  importlib("stdole2.tlb");

  interface IPluginInfo;
  interface ICoreInfo;


  [
    uuid(631B96BB-1E7E-407D-83F1-5C673D2B5A15),
    version(1.0)
  ]
  interface IPluginInfo: IUnknown
  {
    [propget, id(0x00000065)]
    HRESULT _stdcall ID([out, retval] struct GUID* Value);
    [propget, id(0x00000066)]
    HRESULT _stdcall Name([out, retval] BSTR* Value);
    [propget, id(0x00000067)]
    HRESULT _stdcall Version([out, retval] BSTR* Value);
  };

  [
    uuid(3BAA3534-5422-42B9-BDEA-1CE1037295B3),
    version(1.0)
  ]
  interface ICoreInfo: IUnknown
  {
    [propget, id(0x00000065)]
    HRESULT _stdcall Version([out, retval] long* Value);
  };

};

Файлы PluginAPI.tlb и PluginAPI.ridl (или .idl) - это то, что необходимо распространять в составе SDK. Имея на руках эти файлы любой сможет их импортировать в свой любимый язык программирования и получить заголовочные файлы. Вам не нужно ничего переводить самому.

Генерация заголовочников для Delphi и C++ Builder

К примеру, если говорить про Delphi и C++ Builder, то получение нужных файлов (да, это немного бессмысленно, т.к. эти файлы у нас в любом случае есть, но чисто ради примера) удобно делать через утилиту GenTLB.exe в папке bin - вы можете указать ей .ridl файл и на выходе получить комплект из .pas, .hpp и .cpp - все необходимые заголовочники для Delphi и C++. Есть утилита tlibimp.exe, которая работает по .tlb файлу. К примеру, если у вас на руках есть .tlb файл, то получить комплект файлов вы можете такой командой:

tlibimp.exe Source.tlb -C -P -I "-DD:\Output\" -Pt+

Здесь Source.tlb - это исходный файл, а D:\Output\ - папка, куда нужно поместить результаты. Опции -C, -P и -I отвечают за генерацию .hpp/.cpp, .pas и .ridl файлов соответственно, а опция -Pt+ включает красивое "схлопывание" методов-акцессоров в свойства для Delphi.

Кроме того, если вы создадите библиотеку типов в рамках проекта (т.е. вы выберите File\New\ActiveX\Type Library в то время, когда у вас открыт проект основной программы), то необходимые .pas файлы будут сгенерированы (и будут обновляться в дальнейшем) автоматически.

Автогенерируемые файлы получают суффикс "_TLB". Например, библиотека "PluginAPI.tlb" создаст файл "PluginAPI_TLB.pas". Сам файл при этом выглядит примерно так:

unit PluginAPI_TLB;

// ************************************************************************ //
// WARNING                                                                    
// -------                                                                    
// The types declared in this file were generated from data read from a       
// Type Library. If this type library is explicitly or indirectly (via        
// another type library referring to this type library) re-imported, or the   
// 'Refresh' command of the Type Library Editor activated while editing the   
// Type Library, the contents of this file will be regenerated and all        
// manual modifications will be lost.                                         
// ************************************************************************ //

// $Rev: 41960 $
// File generated on 2011.12.25 18:49:13 from Type Library described below.

// ************************************************************************  //
// Type Lib: c:\Users\Александр\Documents\RAD Studio\Projects\Plugins\Example2\PluginAPI\Headers\PluginAPI.tlb (1)
// LIBID: {F156F71A-758A-40E2-A34E-50187B8ED7B9}
// LCID: 0
// Helpfile: 
// HelpString: 
// DepndLst: 
//   (1) v2.0 stdole, (C:\Windows\SysWOW64\stdole2.tlb)
// Cmdline:
//   tlibimp  "c:\Users\Александр\Documents\RAD Studio\Projects\Plugins\Example2\PluginAPI\Headers\PluginAPI.tlb" -C -P -I "-Dc:\Users\Александр\Documents\RAD Studio\Projects\Plugins\Example2\PluginAPI\Headers\Test\" -Pt+
// ************************************************************************ //
{$TYPEDADDRESS OFF} // Unit must be compiled without type-checked pointers. 
{$WARN SYMBOL_PLATFORM OFF}
{$WRITEABLECONST ON}
{$VARPROPSETTER ON}
{$ALIGN 4}

interface

uses Windows, ActiveX, Classes, Graphics, StdVCL, Variants;
  

// *********************************************************************//
// GUIDS declared in the TypeLibrary. Following prefixes are used:        
//   Type Libraries     : LIBID_xxxx                                      
//   CoClasses          : CLASS_xxxx                                      
//   DISPInterfaces     : DIID_xxxx                                       
//   Non-DISP interfaces: IID_xxxx                                        
// *********************************************************************//
const
  // TypeLibrary Major and minor versions
  PluginAPIMajorVersion = 1;
  PluginAPIMinorVersion = 0;

  LIBID_PluginAPI: TGUID = '{F156F71A-758A-40E2-A34E-50187B8ED7B9}';

  IID_IPluginInfo: TGUID = '{631B96BB-1E7E-407D-83F1-5C673D2B5A15}';
  IID_ICoreInfo: TGUID = '{3BAA3534-5422-42B9-BDEA-1CE1037295B3}';
type

// *********************************************************************//
// Forward declaration of types defined in TypeLibrary                    
// *********************************************************************//
  IPluginInfo = interface;
  ICoreInfo = interface;

// *********************************************************************//
// Interface: IPluginInfo
// Flags:     (0)
// GUID:      {631B96BB-1E7E-407D-83F1-5C673D2B5A15}
// *********************************************************************//
  IPluginInfo = interface(IUnknown)
    ['{631B96BB-1E7E-407D-83F1-5C673D2B5A15}']
    function Get_ID: TGUID; safecall;
    function Get_Name: WideString; safecall;
    function Get_Version: WideString; safecall;
    property ID: TGUID read Get_ID;
    property Name: WideString read Get_Name;
    property Version: WideString read Get_Version;
  end;

// *********************************************************************//
// Interface: ICoreInfo 
// Flags:     (0)
// GUID:      {3BAA3534-5422-42B9-BDEA-1CE1037295B3}
// *********************************************************************//
  ICoreInfo = interface(IUnknown)
    ['{3BAA3534-5422-42B9-BDEA-1CE1037295B3}']
    function Get_Version: Integer; safecall;
    property Version: Integer read Get_Version;
  end;

implementation

uses ComObj;

end.

Тут довольно много воды (к примеру, можно подчистить списки uses и удалить к чертям комментарии), но сам код практически дословно повторяет наш исходный вариант. Что и требовалось получить.

Генерация заголовочников для Visual Studio C++

Итак, это был вариант для Delphi и C++ Builder. Чуть более интересно - Visual Studio C++. Во-первых, вам понадобится сама студия. У Microsoft есть обрезанный бесплатный вариант Visual Studio Express - его будет достаточно. Взять его можно тут. Только убедитесь, что берёте именно C++, а не Phone, Basic или C#. Обратите внимание, что по умолчанию при загрузке сайт предлагает установить Trial версии Professional - убедитесь, что вы щёлкните по второму варианту (установка версии Express). Скачается небольшой web-установщик - запускайте его и ставьте. Далее ничего необычного нет.

Я думаю, что импортировать TLB можно и в самой студии, но т.к. я в ней не силён, то мне было проще работать через утилиты командной строки. Если вы знаете другой способ генерации заголовочников по TBL в Visual Studio - ради бога, используйте его. Я же установил Platform SDK (сейчас он называется Windows SDK), который взял тут. Это тоже веб-установщик и устанавливается он как обычно. После этого в SDK нас интересуют утилиты. Во-первых, там есть утилитка OleView.exe (C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\OleView.Exe). Она может открыть .tlb-файл и показать, что там внутри - т.е. это просмотрщик (примечание: если вдруг он почему-то не работает, то скорее всего надо зарегистрировать библиотеку IViewers.Dll в той же папке). Плюс, он умеет экспортировать библиотеку типов в .idl, .h и .c. Вот этим и нужно воспользоваться. Открываете свою библиотеку типов и экспортируете её в заголовочники.

По правде сказать, в .idl он у меня сконвертировал, а вот в .h и .c - нет. Мелькнувшее окошко консоли ругнулось на то, что он не может найти cl.exe - это препроцессор C, который идёт в комплекте с Visual Studio. Я не уверен, почему это происходит у меня, заставить его работать я так и не смог (ладно, особо упорно я и не старался). Поэтому я пошёл другим путём: я создал .bat файл с таким содержанием:

@echo off
call "c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat"
"c:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\Midl.Exe" "c:\Test\PluginAPI.IDL" /out "C:\Test\Out" /h "PluginAPI.hpp"

(где IDL файл - это текстовое представление библиотеки типов; я не пробовал с файлами, генерируемыми Delphi; этот IDL файл - тот, что мне выдал OLEView).

MIDL компилятор по IDL файлу сгенерировал мне PluginAPI.hpp и PluginAPI_i.c - это и есть нужные нам файлы.

Выводы по ведению заголовочных файлов

Итак, подводя черту, у вас есть три способа ведения заголовочников:

Просто писать .pas файл и при необходимости вручную перевести его на другие языки.
Создать библиотеку типов и редактировать её в редакторе Delphi (вообще говоря, для этого можно использовать любой редактор TLB, а не только Delphi). В конце автоматически получить .tlb и комплект файлов для Delphi, C++ Builder, Visual Studio C++, а также текстовое описание (idl/ridl).
Создать idl или ridl файл. Писать текст - это быстрее и удобнее, чем использовать редактор, но нужно знать язык описания интерфейсов (IDL). В конце скомпилировать файл в .tlb и получить комплект сопроводительных файлов.

Как делать - на ваш выбор. В принципе, начать можно с п1, а затем перейти к п2 или п3, но надо понимать, что при этом вы будете дублировать свою работу (сначала вы пишете .pas, а потом ровно это же воспроизводите в библиотеке типов). Так что изначально начав работу с библиотекой типов вы избежите повторения. Тем не менее, именно по этой причине (поскольку одно тождественно второму), здесь и далее я буду говорить только про Паскаль и приводить код только Delphi модулей - подразумевая, что для других языков вы либо сделаете перевод, либо составите .tlb-файл. Но я больше не буду заострять на этом внимание. Итак, всюду ниже вы делаете как написано, но в итоге собираете файлы для других языков. Надеюсь, это понятно.

Давайте я ещё просуммирую действия, которые вам необходимо делать при работе с TLB:

Помещайте .tlb файлы в PluginsAPI\Headers. .tlb файл - это главный и основной файл. Его нужно распространять обязательно. Все остальные пункты ниже - необязательные. Их можно не делать. Но если вы их сделаете, то это будет дополнительное удобство.
В папку PluginsAPI\Headers положите файлы .idl или .ridl.
Получите комплект заголовочников для Delphi, C++ Builder и Visual Studio C++, как указано выше (tlibimp для Delphi и C++ Builder и oleview/midl для Visual Studio).
В папке PluginAPI\Headers создайте подпапки Delphi, Builder и VC.
В папку Delphi положите XYZ_TLB.pas
В папку Builder положите XYZ_TLB.h и XYZ_TLB.cpp
В папку VC положите XYZ.hpp и XYZ_i.c

Папка PluginAPI\Headers целиком (с подпапками) - это то, что вам нужно распространять среди разработчиков ваших плагинов.

Далее мы к этому возвращаться не будем.

Что касается файла PluginAPI.pas с двумя типами данных и двумя константами - вы можете описать его словами в документации, плюс приложить вот это определение на C:

//-- type declarations -------------------------------------------------------
typedef HRESULT __stdcall (*TInitPluginFunc)(IUnknown *ACore, IUnknown **Result);
typedef HRESULT __stdcall (*TDonePluginFunc)(void);

//-- var, const, procedure ---------------------------------------------------
#define SPluginInitFuncName L"87D4EDFB420343F2976EB3CF4DB7C224"
#define SPluginDoneFuncName L"87D4EDFB420343F2976EB3CF4DB7C224_done"
#define SPluginExt L".MyAppPlugin"

Этого будет достаточно, чтобы разработчики плагинов поняли бы, о чём идёт речь, и что нужно делать. Конечно, разработчикам на других языках (не C++ и не Delphi) придётся перевести эти строки на свой язык самостоятельно, но перевод пары строк - это полный пустяк. Основную массу заголовочников транслировать не нужно - для этого есть импорт библиотеки типов.

Далее, в документации нужно особо уточнить, что ваши плагины и ядро - это не COM-объекты. Просто самое типичное использование библиотеки типов - это COM. Т.е. если кто-то видит библиотеку типов, он может автоматически потянуться её импортировать и вызывать CoCreateInstance для создания объектов. Только это не будет работать в вашем случае. Потому что у вас нет никаких COM-объектов, и уж тем более их никто глобально не регистрировал, чтобы их можно было получить через CoCreateInstance. Поэтому нужно чётко указать: это не COM, библиотека типов служит лишь для авто-генерации заголовочных файлов для вашего любимого языка программирования, а чтобы сделать плагин - нужно создать DLL с двумя вот такими (см. C код выше) функциями. Первая из которых работает с интерфейсами. Какими интерфейсами? А вот они как раз описаны в библиотеке типов.

Как-то так.

Начала реализации функциональности

Итак, вернёмся же к нашим баранам. Я напомню, что мы решили дать возможность плагину и ядру узнать информацию друг о друге и для этого мы ввели такие интерфейсы:

type
  IPluginInfo = interface
  ['{F96EFCD5-17F6-4C17-956C-219F23C51AF9}']
  // private
    function GetID: TGUID; safecall;
    function GetName: WideString; safecall;
    function GetVersion: WideString; safecall;
  // public
    property ID: TGUID read GetID;
    property Name: WideString read GetName;
    property Version: WideString read GetVersion;
  end;

  ICoreInfo = interface
  ['{525797CF-89EB-4226-8BFE-4E3DD2123E13}']
  // private
    function GetVersion: Integer; safecall;
  // public
    property Version: Integer read GetVersion;
  end;

Я написал их от балды - вы можете использовать любую другую структуру, даже один интерфейс вместо двух (скажем, IVersionInfo). Тут ничего жёстко не определено, работает ваша фантазия - как захотите, так и сделаете. Я бы только рекомендовал предусмотреть идентификацию плагинов по уникальному ID. В качестве такого хорошо подходит GUID. А вот имя файла - не достаточно (плагин можно переименовать).

В любом случае, теперь их надо использовать в коде. Начнём с плагина. Возьмём пустой плагин из предыдущего примера и дополним его новым кодом следующим образом:

library Plugin1;

uses
  SysUtils,
  Classes,
  PluginAPI in 'PluginAPI\Headers\PluginAPI.pas',
  PluginAPI_TLB in 'PluginAPI\Headers\Delphi\PluginAPI_TLB.pas';

{$R *.res}

const
  SPluginID: TGUID = '{C147E26F-3933-4AE2-A4A8-2A55BC9DABD2}';
  SPluginName      = 'Example plugin';
  SPluginVersion   = '1.0.0.0';

type
  TPlugin = class(TInterfacedObject, IUnknown, IPluginInfo)
  private
    FCore: ICoreInfo;
  protected
    function Get_ID: TGUID; safecall;
    function Get_Name: WideString; safecall;
    function Get_Version: WideString; safecall;
  public
    constructor Create(const ACore: IInterface);
  end;

{ TPlugin }

constructor TPlugin.Create(const ACore: IInterface);
begin
  inherited Create;
  if not Supports(ACore, ICoreInfo, FCore) then
    Assert(False);
  Assert(FCore.Version >= 1);
end;

function TPlugin.Get_ID: TGUID;
begin
  Result := SPluginID;
end;

function TPlugin.Get_Name: WideString;
begin
  Result := SPluginName;
end;

function TPlugin.Get_Version: WideString;
begin
  Result := SPluginVersion;
end;

// _________________________________________________________________

function Init(const ACore: IInterface): IInterface; safecall;
begin
  Result := TPlugin.Create(ACore);
end;

procedure Done; safecall;
begin

end;

exports
  Init name SPluginInitFuncName,
  Done name SPluginDoneFuncName;

end.

Итак, плагин реализует интерфейс IPluginInfo - для этого нам понадобился объект. Реализация методов в данном случае тривиальна - мы просто возвращаем константы. Конструктор объекта получает из переданного нам интерфейса интерфейс ICoreInfo и сохраняет его в поле FCore. Это не нужно в этом примере (нигде ниже FCore не используется), но может быть полезно в общем случае. После получения интерфейса, мы проверяем, что версия ядра - 1 или выше. Конечно, это всегда будет так. Глупая проверка :)

Кстати, я выбрал строку для версии плагина, подразумевал, что единственное, что с ней можно сделать - показать в интерфейсе пользователя. Поэтому строка. С другой стороны, версия ядра не показывается (плагином) в UI, но нужна ему для проверки, есть ли у ядра интересующие плагин возможности. Вот почему это число - для простой проверки. К примеру, если в будущем мы расширим наше ядро новыми возможностями, то плагин при загрузке может проверить, что версия ядра не ниже двух - и отказаться грузиться в старой версии программы (потому что там нет новых возможностей, которые нужны плагину). Ладно, в любом случае сейчас это никак не используется, потому что у нас всего одна версия. Но это пример на будущее.

Теперь, что касается ядра.

unit PluginManager;

interface

...

  IPlugin = interface
  // protected
    ...
    function GetID: TGUID;
    function GetName: String;
    function GetVersion: String;
  // public
    ...
    property ID: TGUID read GetID;
    property Name: String read GetName;
    property Version: String read GetVersion;
  end;

  IPluginManager = interface
  // protected
    ...
  // public
    ...
    procedure SetVersion(const AVersion: Integer);
  end;

...

implementation

uses
  Registry,
  PluginAPI,
  PluginAPI_TLB;

...

type
  TPluginManager = class(TInterfacedObject, IUnknown, IPluginManager, ICoreInfo)
  private
    ...
    FVersion: Integer;
  protected
    ...
    procedure SetVersion(const AVersion: Integer);
    function Get_Version: Integer; safecall;
  public
    ...
  end;

  TPlugin = class(TInterfacedObject, IPlugin)
  private
    ...
    FInfoRetrieved: Boolean;
    FID: TGUID;
    FName: String;
    FVersion: String;
    procedure GetInfo;
  protected
    ...
    function GetID: TGUID;
    function GetName: String;
    function GetVersion: String;
  public
    ...
  end;

{ TPluginManager }

constructor TPluginManager.Create;
begin
  ...
  SetVersion(1);
end;

...

procedure TPluginManager.SetVersion(const AVersion: Integer);
begin
  FVersion := AVersion;
end;

function TPluginManager.Get_Version: Integer;
begin
  Result := FVersion;
end;

...

procedure TPlugin.GetInfo;
var
  Info: IPluginInfo;
begin
  if FInfoRetrieved then
    Exit;
  if Supports(FPlugin, IPluginInfo, Info) then
  begin
    FID := Info.ID;
    FName := Info.Name;
    FVersion := Info.Version;
    FInfoRetrieved := True;
  end;
end;

function TPlugin.GetID: TGUID;
begin
  GetInfo;
  Result := FID;
end;

function TPlugin.GetName: String;
begin
  GetInfo;
  Result := FName;
end;

function TPlugin.GetVersion: String;
begin
  GetInfo;
  Result := FVersion;
end;

Изменения в основной программе (показываем имя плагина и его версию вместо имени файла):

procedure TMainForm.UpdatePluginsList;
var
  X: Integer;
begin
  ListBox1.Items.BeginUpdate;
  try
    ListBox1.Items.Clear;
    for X := 0 to Plugins.Count - 1 do
      ListBox1.Items.Add(IntToStr(Plugins[X].Index) + ': ' + Plugins[X].Name + ' (' + Plugins[X].Version + ')');
  finally
    ListBox1.Items.EndUpdate;
  end;
end;

Теперь пояснения по коду. Здесь я практически продублировал интерфейс IPluginInfo из заголовочника в IPlugin. Плюсы: вы посмотрите, как красиво выглядит код в основной программе! Можно подумать мы с компонентами работаем, а не с плагинами. Минусы: нам пришлось писать кучу кода-обёртки, который мне сейчас придётся объяснять.

Подобное дублирование делать необязательно и в следующий раз я покажу другой пример.

Сам код для информации о плагине состоит из трёх однотипных методов (GetID, GetName, GetVersion). По сути, здесь показан пример получения информации по запросу: мы не вызываем интерфейс IPluginInfo до тех пор, пока кто-то не обратится к одному из свойств плагина (ID, Name, Version). Это можно было бы делать и по другому: запросить информацию в конструкторе TPlugin. Кроме того, этот код показывает пример кэширования информации: когда мы получили информацию, мы сохранили её в полях объекта (кэше). Если она потребуется нам повторно - нам не придётся дёргать плагин снова, чтобы её получить. Этот подход отлично подходит для статической информации (которая не меняется), но мало пригоден для динамической.

Что касается интерфейса ICoreInfo, то его реализует менеджер плагинов. Тут есть такой вопрос: вообще-то менеджер плагинов не в курсе, что за версия у ядра. Это знает ядро, а не менеджер плагинов. Поэтому мы по умолчанию ставим версию 1. А ядру даёт метод SetVersion, с помощью которого оно сможет установить (при необходимости) номер версии 2, 3 и так далее. Обратите внимание, что хотя методы SetVersion и Get_Version и выглядят парой (и, по сути, это методы-акцессоры Get и Set для свойства "Версия"), они имеют существенное отличие: метод Get предназначен для плагинов, а метод Set - для ядра (это видно по соглашению вызова: safecall и register). Метод SetVersion плагин вызвать не может!

В связи с тем, что у нас появился интерфейс ядра, который мы передаём плагину, у нас возникла небольшая проблема: как вы помните из сказанного выше, плагины не выгружаются программой явно, они выгружаются при удалении менеджера плагинов. А наш менеджер плагинов удаляется тогда, когда все ссылки на него будут уничтожены. Последняя из которых (ссылка) обнуляется в finalization модуля менеджера. А проблема тут вот в чём: мы ведь передали интерфейс менеджера плагинам. Это означает, что обнуление ссылки в секции finalization не будет последним: ведь ссылку на менеджер держат плагины, которые... не выгружаются потому, что менеджер ещё жив. Вот и получается круговая ссылка: менеджер ссылается на плагины, а плагины - на менеджер. И никто из них выгружаться не хочет, потому что есть активные ссылки. Вот поэтому нам нужно внести изменение: в секции finalization нужно явно скомандовать менеджеру плагинов выгрузить все плагины. Сделать это можно просто финализировав массив FItems - всё остальное за нас сделает механизм учёта ссылок. Финализация массива уничтожит каждый его элемент, каждый элемент - это плагин. Т.е. каждый плагин будет выгружен. Выгрузка плагина отпустит ссылку на менеджер плагинов, после чего обнуление ссылки на менеджер плагинов в секции finalization уничтожит его - и все будут довольны. Код я тут выписывать не буду - там всего несколько строк.

На этом пора бы подвести черту основному введению в разработку системы плагинов на Delphi. Код к этому моменту можно скачать тут. Нужно отметить, что весь этот код не имеет специфики, он универсален. А потому он может использоваться как база для ваших программ. В следующей статье мы начнём делать уже конкретные вещи и реально полезные плагины. Поэтому код в следующей части не может быть использован в вашем коде, а служит только лишь примером.

Примерный список вопросов для рассмотрения в следующий раз: обработка ошибок, функциональность в плагине, обращение из плагина к внутренностям ядра, общение плагинов между собой, показ плагинами UI, обратные вызовы (инициация действий плагином, а не ядром).

Публичная бета EurekaLog 7

2011-12-20T02:47:00.001+04:00

Получи бесплатную лицензию на EurekaLog 7! ;)

Компания EurekaLab s.a.s. объявляет о начале публичного бета-тестирования EurekaLog 7.

Вы можете скачать бету из секции "Delphi downloads" на веб-сайте.

Вам также предлагается пройти краткий опрос. Опрос займёт не более 10 минут и здорово поможет EurekaLab в будущем. Вы можете пройти опрос тут (на английском).

Как попробовать EurekaLog 7

EurekaLog 7 может быть установлена вместе с EurekaLog 6. Вы можете переключаться между версиями EurekaLog, используя новый пункт меню "Manage" в меню Пуск/Программы.

Для более подробной информации - см. эту статью (на английском).

Отличия от EurekaLog 6

EurekaLog 7 достаточно похожа на EurekaLog 6 и работать с ней нужно по тем же принципам. Единственное важное отличие для быстрого старта - в EurekaLog 7 после её включения для проекта, вам также нужно указать тип вашего приложения.

Пожалуйста, пройдитесь по Quick Start Tutorials для быстрого ознакомления с изменениями.

EurekaLog 7 в существующих (старых) проектах под EurekaLog 6

EurekaLog 7 меняет некоторое поведение и вносит новые возможности. С целью сохранения обратной совместимости был введён так называемый "режим совместимости с EurekaLog 6" ("EurekaLog 6 Compatibility Mode"). Вы можете включить или выключить его на вкладке "General" в меню опций EurekaLog для проекта.

Идея режима в том, что если вы его включаете, то EurekaLog будет вести себя так же, как EurekaLog 6. Так что вам не нужно будет менять свой старый код. Если вы его выключаете, то EurekaLog 7 использует новое поведение. Когда вы открываете старый проект - он открывается (импортируется) в режиме "EurekaLog 6 Compatibility Mode". Если же вы создаёте новый проект - он будет создан с выключенным режимом "EurekaLog 6 Compatibility Mode".

Где искать информацию

В EurekaLog 7 была значительно расширена справочная система, но она всё ещё находится в процессе написания. Справку можно открыть локально (через меню Пуск или кнопку F1 в любом окне EurekaLog) или онлайн.

Документация на код ещё пишется, но вы можете изучить заголовочные файлы в вашей папке \Source (по умолчанию это C:\Program Files (x86)\EurekaLab\EurekaLog 7\Source\). Полный исходный код будет доступен только в редакции Enterprise, но частичный исходных код доступен в любой редакции (включая Trial)!

Я также могу писать заметки в блоге, освещающие изменения или новые возможности в EurekaLog 7.

Список изменений в EurekaLog 7 можно посмотреть тут (на английском; список ещё пишется).

Участвуй в бета-тесте - выиграй лицензию EurekaLog!

Для тех, кто примет участие в бета-тестировании EurekaLog 7 приготовлен подарок. Самые активные тестеры получат бесплатную лицензию EurekaLog 7 Enterprise! (и, возможно, лицензии других редакций - в качестве поощрительного приза) Это предложение доступно всем - как существующим клиентам EurekaLab s.a.s., так и новым пользователям EurekaLog.

Так что же вам нужно для этого делать? Просто установите EurekaLog 7 и начните её использовать. Сообщайте о каждом замеченном баге. Или просто поделитесь мнением или внесите предложение. Или пришлите код или иной вклад в проект. Чем больше полезной информации вы пришлёте - тем больше ваши шансы на выигрыш.

Как отправлять информацию? Вы можете либо использовать встроенные средства отправки, либо воспользоваться этой веб-формой. Убедитесь, что вы отправляете все свои сообщения с одного e-mail адреса. В случае вашей победы ваша лицензия на EurekaLog будет зарегистрирована на этот адрес. Пожалуйста, не используйте для этого форумы и не шлите сообщения мне лично (пожалуйста, не надо мне слать любые сообщения лично, даже если вы не собираетесь участвовать в конкурсе). Короче говоря, если вы получили авто-ответ от нашей системы тех-поддержки о регистрации вашего сообщения - оно будет участвовать в этом конкурсе. Отзывы можно писать на русском языке - с хорошей долей вероятности разбирать их буду я лично. Но даже если нет - остальные члены команды могут использовать Google Translate.

Победители будут объявлены после выхода стабильной (финальной) версии EurekaLog 7. Число победителей не ограничено и будет установлено в зависимости от числа бета-тестеров. Победители будут определены как внёсшие наиболее полезный вклад в развитие проекта. "Полезность" будет определяться разработчиками EurekaLog на их усмотрение. К примеру, один подробный отчёт будет ценится больше нескольких односложных отчётов (однако это не значит, что вам нужно добавлять в отчёты воду). Правила и условия этого предложения могут быть изменены в будущем.

Если вы не выиграете лицензию - вы всё ещё сможете обновить вашу текущую лицензию на EurekaLog с 50% скидкой. Либо даже получить её бесплатно, если вы купили лицензию на EurekaLog 6 за 90 дней до выхода EurekaLog 7.

Примечание: дата выхода EurekaLog 7 не установлена. Она выйдет тогда, когда будет готова. Вы можете ускорить это событие, потестировав бету.

Примечание: сейчас доступна только редакция Trial (которую можно скачать с веб-сайта). Другие редакции (вроде Professional и Enterprise) станут доступны только после выхода стабильной версии EurekaLog 7.

Предупреждение: это первая бета EurekaLog. Крайне не рекомендуется использовать её в релиз-версиях ваших реальных проектов.

P.S. Ах, да, российская специфика: вы можете присылать отзывы, даже если вы пират.

Сериализация - потоки данных

2011-11-12T23:57:00.001+04:00

Это второй пост в серии постов про сериализацию. В этой части мы рассмотрим потоки данных.

Общие сведения
Общие принципы работы
Обработка ошибок
Правила использования
Практика
Особенности:
Создание своих классов-потоков
Преимущества и недостатки потоков данных

Общие сведения

Если вы вспомните определение файла, то оно звучало так: "файл - это устройство с последовательным доступом, к которому можно обратиться по имени". При этом физические файлы на диске являются лишь частным случаем. Отнимите из этого определения часть "имеющие имя" - и вы получите определение потока данных. Поток данных представляет собой "что-то" с последовательным доступом. Вы можете читать из него данные или записывать. Некоторые потоки поддерживают позиционирование (вроде физического файла на диске), другие - нет (вроде сетевого сокета).

Потоки данных являются де-факто стандартом для обмена данными в Delphi. Всюду в своих процедурах, где вам необходимо принимать или отправлять нетипизированный набор данных, используйте потоки данных. Многие механизмы Delphi по умолчанию умеют работать именно с потоками данных, предоставляя методы вроде LoadFromStream и SaveToStream (и иногда предоставляя к ним обёртки-переходники вроде LoadFromFile и SaveToFile).

Примечание: поток данных (stream) не следует путать с потоком кода (thread), который также иногда называют нитью. Они не имеют между собой ничего общего, кроме слова "поток" в названии. Если какой-то текст говорит про "потоки", не уточняя кода или данных, то значение термина должно быть ясно из контекста. Эти понятия не пересекаются, так что здесь не должно быть никаких проблем с пониманием. Замечу, что подобная путаница возможна только в русском языке, где два разных понятия переводятся одинаково. В английском языке для них используются разные слова (stream и thread).

В Delphi все потоки данных реализованы как объекты (экземпляры) классов, наследуемых от TStream. TStream является абстрактным базовым классом, который поддерживает операции чтения, записи и позиционирования, но сам при этом не умеет делать ничего. Конкретная работа реализуется его классами-наследниками.

В Delphi есть широкий набор классов, предназначенный для работы с чем угодно: от файла на диске до блока памяти. Каждый такой класс-наследник реализует базовые методы TStream по-своему. К примеру, при чтении из потока данных: наследник для работы с файлами вызовет функцию чтения данных с диска, а наследник для работы с блоком памяти использует процедуру Move для копирования данных.

Вот (неполный) список классов-наследников TStream (примеры):

TFileStream (для работы с файлами)
TResourceStream (для работы с ресурсами программы)
TStringStream (для работы со строками)
TMemoryStream (для работы с буфером в памяти)
TBlobStream (для работы с BLOB полями)
TWinSocketStream (для работы с сетевым сокетом)

По сравнению с прошлой темой, где было всего три вполне конкретных файловых типа, это может быть немного непонятно: зачем нужен какой-то абстрактный класс и классы-наследники? Очень просто: пусть вы хотите уметь загружать растровые изображения (bitmap). Но ведь рисунок может лежать не только в файле, он может быть и в ресурсах программы и в памяти. Не писать же три разных метода, которые делают одно и то же? Вот поэтому и нужен абстрактный класс. Он объявляет общий контракт, которому обязуются следовать все его наследники. Поэтому вы можете спокойно написать (один раз) код, который грузит рисунок из TStream. А уж вызывающий подставит вам TFileStream для загрузки рисунка из файла, TResourceStream для загрузки из ресурса и TMemoryStream для загрузки из памяти. В определённом смысле все эти классы-наследники представляют собой простые переходники (от общей спецификации, определённой TStream, до конкретного метода доступа: файл, ресурс, память, сеть и так далее; и наоборот). В общем, полиморфизм в действии.

Здесь и ниже я буду говорить в основном про физические файлы и примеры приводить в расчёте на TFileStream - как наиболее типичный случай. Просто имейте в виду, что всё сказанное будет применимо и к другим потокам данных.

Кроме того, потоки обеспечивают поддержку для загрузки/сохранения компонентов и форм. Именно благодаря этому механизму работает загрузка .dfm файлов в run-time. Этот механизм работает автоматически. Впрочем, вы можете использовать его и в своих целях. Но на это мы посмотрим в другой раз, потому что он тесно связан с RTTI. Это будет темой одной из следующих статей.

Общие принципы работы с потоками данных

Чтение/запись
Класс TStream имеет два метода для чтения данных и два метода для записи данных. Работают они обычным образом: поток читает (или пишет) указанный блок данных и сдвигает текущую позицию на размер блока данных, так что следующая операция начинается там, где закончилась предыдущая. Ничего сложного.

Итак, для чтения класс TStream предлагает методы Read и ReadBuffer, а для записи - методы Write и WriteBuffer. Эти методы используются одинаково: первым параметром указывается буфер (это нетипизированный параметр), а вторым параметром - его размер в байтах, например:

procedure LoadFromStream(AStream: TStream);
var
  I: array of Integer; 
begin
  // Чтение содержимого AStream в массив I
  SetLength(I, AStream.Size div SizeOf(I[0]));
  AStream.ReadBuffer(I[0], AStream.Size);

  // <- тут какая-то работа с I
end;

procedure SaveToStream(AStream: TStream);
var
  I: array of Integer; 
begin
  // <- тут какая-то работа с I

  // Запись массива I в поток данных AStream 
  AStream.WriteBuffer(I[0], Length(I) * SizeOf(I[0]));
end;

Разница между методами с "Buffer" и без него заключается в том, что методы с суффиксом "Buffer" гарантируют выполнение операции до конца. Если же это невозможно (к примеру, в файле 12 байт, а вы командуете прочитать 24 байта), то будет возбуждено исключение (см. также ниже раздел про обработку ошибок).

А вот методы без суффикса "Buffer" допускают частичное выполнение операции. Они никогда не возбуждают ошибку, а вместо этого возвращают, сколько реально байт было прочитано или записано. Иногда, это может быть и 0 байт. К примеру, если в файле 12 байт, а вы вызываете Read, указывая 24 байта, то метод Read прочитает 12 байт и вернёт вам число 12 (это метод-функция). Ещё пример: если у вас поток связан с сетевым сокетом и вы вызываете Read, но пока никаких данных ещё не пришло: метод завершится тут же, возвращая 0.

Замечу, что некоторые потоки данных могут быть только для чтения или только для записи. К примеру, однонаправленный pipe может не допускать чтения, а ресурсы, очевидно, не разрешают запись. В таких случаях попытка вызова запрещённого метода приведёт к ошибке.

Помимо общих методов чтения/записи, потоки поддерживают специализированные методы для реализации чтения/записи компонентов - но, как я уже сказал, это тема для следующего раза.

Разумеется, некоторые из наследников TStream могут вводить свои специальные методы для чтения/записи. Мы посмотрим на некоторые примеры ниже.

Кроме чтения и записи TStream имеет и некоторые другие методы.

Позиционирование
Во-первых, это методы позиционирования. Вы можете вызвать свойство Size, которое вернёт вам размер потока данных в байтах (кроме того, вы можете устанавливать свойство Size, чтобы менять размер потока, но это поддерживается далеко не всеми видами потоков данных). Свойство Position указывает текущую позицию в потоке данных, где 0 соответствует началу, а значение, равное Size, - концу. Вы можете читать свойство Position, чтобы узнать текущую позицию, и записывать значение в Position, чтобы изменить текущую позицию (позиционирование поддерживается не всеми видами потоков). К примеру:

var
  Stream: TStream;
  SavedPos: Int64;
begin
  ...
  SavedPos := Stream.Position; // Где мы сейчас?
  Stream.Position := 0; // Перешли в начало потока данных
  // что-то сделали...
  Stream.Position := SavedPos; // Вернулись, где были до этого
  ...
  Stream.Position := Stream.Size; // Перешли в конец потока
  ...
end;

Кроме абсолютного позиционирования через свойство Position, потоки данных поддерживают относительное позиционирование в стиле файловых Seek-процедур: метод Seek. Этот метод имеет два параметра: позицию и точку отсчёта. Причём последнее может иметь значения soBeginning (отсчёт от начала потока, аналог абсолютного позиционирования), soCurrent (отсчёт от текущей позиции, относительное смещение) и soEnd (отсчёт от конца потока). Для soCurrent позиция может быть и положительным числом (смещение в сторону конца потока) и отрицательным (смещение в сторону начала), для soBeginning смещение может быть только положительным (или нулём), а для soEnd - только отрицательным (или нулём). Есть также устаревшие константы вида soFromBeginning, soFromCurrent, soFromEnd - не используйте их в новом коде. При этом метод Seek возвращает предыдущее значение текущей позиции (до позиционирования). К примеру:

var
  Stream: TStream;
  SavedPos: Int64;
begin
  ...
  SavedPos := Stream.Seek(0, soBeginning); // Перемещаемся в начало потока, одновременно сохраняя (старую) текущую позицию
  // что-то сделали...
  Stream.Seek(SavedPos, soBeginning); // Вернулись, где были до этого
  ...
  Stream.Seek(0, soEnd); // Перешли в конец потока
  ...
end;

Копирование
У TStream есть ещё один метод: CopyFrom. Этот метод копирует указанное количество данных (в байтах) из указанного массива. Копирование производится с текущей позиции. Метод работает аналогично методу записи WriteBuffer, сдвигая текущую позицию на указанное количество байт и возбуждая исключение при ошибках. Использование CopyFrom позволяет избежать создания буфера, чтения в него данных из исходного потока, запись буфера в выходной поток и удаления буфера - все эти действия выполняются автоматически внутри метода CopyFrom. К примеру, вот простейший пример копирования файлов (см. ниже описание TFileStream):

procedure CopyFile(const ASourceFileName, ATargetFileName: String);
var
  Source: TFileStream;
  Dest: TFileStream;
begin
  // Открыли исходный файл на чтение
  Source := TFileStream.Create(ASourceFileName, fmOpenRead or fmShareDenyWrite);
  try
    // Создали целевой файл (в режиме записи)
    Dest := TFileStream.Create(ATargetFileName, fmCreate or fmShareExclusive);
    try
      // Копируем данные из потока в поток
      Dest.CopyFrom(Source, Source.Size);
    finally
      FreeAndNil(Dest);
    end; 
  finally
    FreeAndNil(Source);
  end;
end;

У CopyFrom есть специальный случай: если последний параметр (размер) равен 0, то CopyFrom скопирует весь поток целиком - начиная с начала потока (вне зависимости от текущей позиции) и до конца. Так что если число байт для записи у вас не фиксировано, а как-то вычисляется, то вставьте перед вызовом CopyFrom проверку на 0: иначе вы скопируете поток целиком вместо 0 байт.

Обработка ошибок

Здесь нет ничего сложного, потоки данных используют стандартную обработку исключений. Вы можете просто писать код, не производя проверок - он по умолчанию будет иметь обработку ошибок. Конечно же, вам нужно использовать try..finally для корректной обработки утечек ресурсов программы:

// Случай 1: код в рамках одной процедуры.

begin
  Stream := ???.Create(...);
  try
    // Работа с потоком
  finally
    FreeAndNil(Stream);
  end;
end;

...

// Случай 2: использование в конструкторах и деструкторах объектов.

constructor TSomeClass.Create;
begin
  inherited Create;
  FStream := ???.Create(...);
end;

procedure TSomeClass.DoSomething;
begin
  // Работа с потоком
end;

destructor TSomeClass.Destroy;
begin
  FreeAndNil(FStream);
  inherited Destroy;
end;

...

SomeObj := TSomeClass.Create;
try
  SomeObj.DoSomething;
finally
  FreeAndNil(SomeObj);
end;

Во втором примере try..finally не используется при работе с потоком, потому что он вынесен во внешний код (вызывающий).

Все исключения, возбуждаемые самим потоком, наследуются от EStreamError. Наиболее типичными случаями являются ошибки EFileStreamError, EFCreateError, EFOpenError, EReadError и EWriteError.

Так что код обработки исключений потоков данных (если он вам нужен) может выглядеть как-то так:

try
  Stream := ???.Create(...);
  try
    // Работа с TStream
  finally
    FreeAndNil(Stream);
  end;
except
  on E: EStreamError do
    Application.MessageBox(PChar(Format('При работе с потоком произошла ошибка %s', [E.Message])), 'Ошибка', MB_OK or MB_ICONERROR);
end;

Всё вышеуказанное - это типичное поведение для работы с исключениями. Тут не должно быть ничего нового и нетипичного.

Так что единственное "ага!" в обработке ошибок - разница между Read и ReadBuffer и между Write и WriteBuffer. Запомните, что если вы вызываете методы без суффикса "Buffer", то вы должны либо явно проверять результат их вызова (прямо как с кодом на кодах ошибок), либо иметь в виду, что данные могут прочитаться/записаться не полностью.

Правила использования

Хотелось бы сказать о "правилах использования" - а, скорее, о наиболее типичных ошибках новичков при работе с потоками данных.

(Почти) всегда используйте ReadBuffer и WriteBuffer. Используйте Read и Write только если вам не важно выполнение операции до конца (к примеру, вы не знаете, сколько данных нужно прочитать). Иными словами, ReadBuffer и WriteBuffer должны быть вашим вариантом по умолчанию, а не наоборот.
Если вы в своей процедуре принимаете или отправляете какие-то данные - используйте TStream. Не используйте для этого нетипизированные параметры, указатели или конкретные экземпляры TStream. Т.е. вместо:
```
procedure A(AData: Pointer; ADataSize: Cardinal);
procedure B(const AData; ADataSize: Cardinal);
procedure C(AData: TFileStream);
```
должно быть:
```
procedure A(AData: TStream);
procedure B(AData: TStream);
procedure C(AData: TStream);
```

Частая ошибка новичков: они забывают про позиционирование. К примеру:

Stream.WriteBuffer(MyData, SizeOf(MyData)); // записали данные для объекта Obj
Obj.LoadFromStream(Stream); // ошибка: загрузка объекта "из конца потока"

Должно быть:

Stream.WriteBuffer(MyData, SizeOf(MyData)); // записали данные для объекта Obj
Stream.Position := 0; // сместились к началу потока
Obj.LoadFromStream(Stream); // правильно: загрузка того, что мы только что записали

TStream является абстрактным классом. Это значит, что в вашем коде не должно быть строк вида TStream.Create. Вы всегда должны использовать конкретного наследника - например, TFileStream или TResourceStream. Если вам нужен "просто поток", то вы можете использовать TMemoryStream - это создаст поток в памяти программы. Если при этом вы хотите использовать большой объём данных, то вы можете использовать TFileStream для временного файла. См. также.
Не забывайте, что потоки работают с большими данными, поэтому всё позиционирование осуществляется на базе Int64 (8 байт/64 бита), а не Integer (4 байта/32 бита). Поэтому если вы по недосмотру где-то используете для позиционирования выражение/переменную типа Integer, то этим вы автоматически ограничите свои данные 2 Гб. Но этот момент также зависит и от вида используемого потока. К примеру, в 32-битных приложениях TMemoryStream не может работать с памятью больше 4 Гб, а TResourceStream ограничен 2 Гб - потому что он работает с ресурсами в исполняемых файлах формата PE. А любой файл формата PE не может быть больше 2 Гб.

Ну и под конец упомяну ещё такой момент: поскольку базовые методы чтения/записи работают с нетипизированными параметрами, то тут возможны ошибки при использовании динамических типов и указателей. Я уже приводил подобный пример в предыдущей статье, но приведу его ещё раз и тут:

var
  StatArray: array[0..15] of Integer;
  DynArray: array of Integer;
  AnsiStr: AnsiString;
  Str: String;
  PCh: PChar;
  Stream: TStream;
... 
  // Неправильно (порча памяти):
  Stream.WriteBuffer(DynArray, Length(DynArray) * SizeOf(Integer));
  Stream.WriteBuffer(AnsiStr, Length(AnsiStr));
  Stream.WriteBuffer(Str, Length(Str) * SizeOf(Char));
  Stream.WriteBuffer(PCh, StrLen(PCh) * SizeOf(Char));
 
  // Правильно (при условии, что размер данных > 0):
  Stream.WriteBuffer(StatArray, Length(StatArray) * SizeOf(Integer));
  Stream.WriteBuffer(StatArray, SizeOf(StatArray));
  Stream.WriteBuffer(StatArray[0], Length(StatArray) * SizeOf(Integer));
  Stream.WriteBuffer(StatArray[0], SizeOf(StatArray));
  Stream.WriteBuffer(Pointer(DynArray)^, Length(DynArray) * SizeOf(Integer));
  Stream.WriteBuffer(DynArray[0], Length(DynArray) * SizeOf(Integer));
  Stream.WriteBuffer(Pointer(AnsiStr)^, Length(AnsiStr));
  Stream.WriteBuffer(AnsiStr[1], Length(AnsiStr));
  Stream.WriteBuffer(Pointer(Str)^, Length(Str) * SizeOf(Char));
  Stream.WriteBuffer(Str[1], Length(Str) * SizeOf(Char));
  Stream.WriteBuffer(PCh^, StrLen(PCh) * SizeOf(Char));
  Stream.WriteBuffer(PCh[0], StrLen(PCh) * SizeOf(Char));
 
  // Неправильно (неверный индекс):
  Stream.WriteBuffer(AnsiStr[0], Length(AnsiStr));
  Stream.WriteBuffer(Str[0], Length(Str) * SizeOf(Char));
  Stream.WriteBuffer(PCh[1], StrLen(PCh) * SizeOf(Char));
 
  // Неправильно (неверный размер 1):
  Stream.WriteBuffer(Pointer(DynArray)^, SizeOf(DynArray));
  Stream.WriteBuffer(DynArray[0], SizeOf(DynArray));
  Stream.WriteBuffer(Pointer(AnsiStr)^, SizeOf(AnsiStr));
  Stream.WriteBuffer(AnsiStr[1], SizeOf(AnsiStr));
  Stream.WriteBuffer(Pointer(Str)^, SizeOf(Str));
  Stream.WriteBuffer(Str[1], SizeOf(Str));
 
  // Неправильно (неверный размер 2):
  Stream.WriteBuffer(Pointer(Str)^, Length(Str));
  Stream.WriteBuffer(Str[1], Length(Str));

Практика

Все примеры ниже приводятся с полной обработкой ошибок. Примеры используют файл в папке с программой. Это удобно для тестирования и экспериментов, но, как указано ранее, этого нужно избегать в реальных программах. После тестирования и перед использованием кода в релизе вы должны заменить папку программы на подпапку в Application Data.

Как вы сейчас увидите, использование базовых методов потоков данных эквивалентно использованию нетипизированных файлов со всеми их преимуществами и недостатками. Впрочем, благодаря классам и наследованию, классы-наследники могут предоставлять другие методы и более удобный доступ для частных случаев - подробнее на это мы посмотрим ниже, а также в следующих статьях цикла. Также мы увидим как ООП предоставляет нам возможность использования некоторых интересных ходов для записи сложных динамических структур данных.

Одно значение: Double

// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Value: Double;
begin
  Value := 5.5;

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    F.WriteBuffer(Value, SizeOf(Value));
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Value: Double;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    F.ReadBuffer(Value, SizeOf(Value));
  finally
    FreeAndNil(F);
  end;

  // Здесь Value = 5.5
end;

Одно значение переменного размера: String
```
// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Value: AnsiString;
begin
  Value := 'Example';

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    F.WriteBuffer(Pointer(Value)^, Length(Value));
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Value: AnsiString;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    SetLength(Value, F.Size);
    F.ReadBuffer(Pointer(Value)^, Length(Value));
  finally
    FreeAndNil(F);
  end;

  // Здесь Value = 'Example'
end;
```
Данный случай прост - размер данных определяется по размеру файла. Для примера я выбрал AnsiString, а не String по друм причинам - во-первых, String - это псевдоним либо на AnsiString, либо на UnicodeString, в зависимости от версии Delphi. Так что вам нужно использовать явные типы - AnsiString, WideString (или UnicodeString), а не String, иначе файл, созданный в одном варианте программы, нельзя будет прочитать в другом варианте программы.

Во-вторых, используя AnsiString, я показал, как вы можете загрузить в строку весь файл целиком, "как есть". Хотя, если подобный подход использовать в реальных программах, то уж лучше использовать array of Byte или хотя бы RawByteString - чтобы подчеркнуть двоичность данных.
Набор однородных значений: array of Double
```
// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Values: array of Double;
  Index: Integer;
begin
  SetLength(Values, 10);
  for Index := 0 to High(Values) do
    Values[Index] := Random * 10;

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    for Index := 0 to High(Values) do
      F.WriteBuffer(Values[Index], SizeOf(Values[Index]));
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Values: array of Double;
  Index: Integer;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    SetLength(Values, F.Size div SizeOf(Values[0]));
    for Index := 0 to High(Values) do
      F.ReadBuffer(Values[Index], SizeOf(Values[Index]));
  finally
    FreeAndNil(F);
  end;

  // Здесь Values тождественно равны исходным данным из Button1Click
end;
```
И снова, благодаря фиксированности размеров элементов, мы можем установить размер массива ещё до чтения из файла. Обратите внимание, что мы могли бы свети этот пример к предыдущему, прочитав/записав весь массив за раз, вместо поэлементного копирования.

Также обратите внимание, что не имеет значения, какой индекс используется внутри выражения у SizeOf. Более того, не требуется даже наличие (существование) этого элемента. Это потому, что мы не обращаемся к нему - мы только просим у компилятора его размер. Это, по сути, константа. Так что всё выражение вообще не вычисляется - оно просто заменяется числом. Это удобный трюк для написания подобного кода, потому что это удобнее, чем писать тип явно: SizeOf(Double). Почему? А что, если мы изменим объявление типа с Double на Single? И забудем обновить SizeOf? Тогда это приведёт к порче памяти - т.к. писаться или читаться будет больше, чем реально есть байт в элементе. Это выглядит не очень страшно для массива из Double, но рассмотрите вариант, скажем, строки - изменение размера Char гораздо более вероятно. А вот если мы используем форму SizeOf как в примере, то такой проблемы не будет - размер изменится автоматически.
Набор однородных значений переменного размера: array of String
```
// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Values: array of String;
  Index: Integer;
  Str: WideString;
  Len: LongInt;
begin
  SetLength(Values, 10);
  for Index := 0 to High(Values) do
    Values[Index] := 'Str #' + IntToStr(Index);

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    for Index := 0 to High(Values) do
    begin
      Str := Values[Index];
      Len := Length(Str);

      F.WriteBuffer(Len, SizeOf(Len));
      if Len > 0 then
        F.WriteBuffer(Str[1], Length(Str) * SizeOf(Str[1]));
    end;
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Values: array of String;
  Str: WideString;
  Len: LongInt;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    while F.Read(Len, SizeOf(Len)) > 0 do
    begin
      SetLength(Str, Len);
      if Len > 0 then
        F.ReadBuffer(Str[1], Length(Str) * SizeOf(Str[1]));

      SetLength(Values, Length(Values) + 1);
      Values[High(Values)] := Str;
    end;
  finally
    FreeAndNil(F);
  end;

  // Здесь Values тождественно равны исходным данным из Button1Click
end;
```
С записью набора динамических данных возникает проблема - как отличить один элемент от другого? Мы не можем более использовать переход на другую строку, как это было с текстовыми файлами. Тут есть несколько вариантов.

Самый простой и очевидный - ввести разделитель данных. Т.е. элементы отделяются друг от друга специальным символом. В качестве такого чаще всего выступает нулевой символ (#0) - это аналог разделителя строк в текстовых файлах. Тогда чтение-запись сведётся к примеру два. Но я не стал показывать этот путь, т.к. он очевидно вводит ограничение на возможные данные: теперь данные не могут содержать в себе разделитель (каким бы вы его ни выбрали). Конечно, вы можете его экранировать, но гораздо проще будет выбор другого подхода.

И я его показал - это явная запись размера данных до записи самих данных. Т.е. мы пишем два значения для каждого элемента: длину и сами данные.

Кроме того, в этом же примере показано, как можно сделать так, чтобы внутри программы работать с хорошо знакомым String, а в файле хранить фиксированный тип (AnsiString/RawByteString или WideString/UnicodeString). Вообще говоря, даже если вы работаете на Delphi 7 или любой другой версии Delphi до 2007 включительно - я бы рекомендовал всегда писать Unicode-данные в формате WideString во внешние хранилища.

Обратите внимание, что в качестве счётчика длины используется LongInt, а не Integer - по причинам, указанным выше для типизированных файлов: String, Extended, Integer и Cardinal могут менять свои размеры в зависимости от окружения - поэтому мы используем другие типы, которые гарантированно всегда имеют один и тот же размер.

Ещё в этом примере показан вариант пример использования метода Read: идея в том, что если будет достигнут конец потока, то вызов метода Read вернёт 0. Т.е. это аналог функции EoF. Альтернативным решением является код
```
    ...
    while F.Position < F.Size do
    begin
      F.ReadBuffer(Len, SizeOf(Len));
      SetLength(Str, Len);
    ...
```
Вы также можете создать вспомогательную функцию
```
function EoS(Stream: TStream): Boolean; // End of Stream
begin
  Result := (F.Position >= F.Size);
end;
    ...
    while not EoS(F) do
    begin
      F.ReadBuffer(Len, SizeOf(Len));
      SetLength(Str, Len);
    ...
```
И тогда этот пример будет эквивалентен примеру для нетипизированных файлов Pascal. Я буду использовать подпрограмму EoS в примерах ниже.

Запись - набор неоднородных данных:

type
  TData = record
    Signature: LongWord;
    Size: LongInt;
    Comment: String;
    CRC: LongWord;
  end;

// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Value: TData;
  Len: LongInt;
  Str: WideString;
begin
  Value.Signature := 123;
  Value.Size := SizeOf(Value);
  Value.Comment := 'Example';
  Value.CRC := 0987654321;

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    F.WriteBuffer(Value.Signature, SizeOf(Value.Signature));
    F.WriteBuffer(Value.Size, SizeOf(Value.Size));
    Str := Value.Comment;
    Len := Length(Str);
    F.WriteBuffer(Len, SizeOf(Len));
    if Len > 0 then
      F.WriteBuffer(Str[1], Length(Str) * SizeOf(Str[1]));
    F.WriteBuffer(Value.CRC, SizeOf(Value.CRC));
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Value: TData;
  Len: LongInt;
  Str: WideString;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    F.ReadBuffer(Value.Signature, SizeOf(Value.Signature));
    F.ReadBuffer(Value.Size, SizeOf(Value.Size));
    F.ReadBuffer(Len, SizeOf(Len));
    SetLength(Str, Len);
    if Len > 0 then
      F.ReadBuffer(Str[1], Length(Str) * SizeOf(Str[1]));
    Value.Comment := Str;
    F.ReadBuffer(Value.CRC, SizeOf(Value.CRC));
  finally
    FreeAndNil(F);
  end;

  // Здесь Value = значениям из Button1Click
end;

В отличие от типизированных файлов, для нетипизированных файлов нет никаких проблем с записью неоднородных данных - вы просто пишете одно за другим. Данные фиксированного размера самодокументируются, а для динамических данных вы пишете сначала их размер, а затем сами данные. При чтении повторяете всё это в обратном порядке.

Кстати, я бы вынес запись динамических данных в отдельные служебные подпрограммы:

procedure WriteBufferDyn(F: TFileStream; const AData: WideString); overload;
var
  Len: LongInt;
begin
  Len := Length(AData);
  F.WriteBuffer(Len, SizeOf(Len));
  if Len > 0 then
    F.WriteBuffer(AData[1], Length(AData) * SizeOf(AData[1]));
end;

procedure WriteBufferDyn(F: TFileStream; const AData: array of Byte); overload;
... 

// и так далее для каждого типа данных переменного размера, который вы используете

procedure ReadBufferDyn(F: TFileStream; out AData: String); overload;
var
  Len: LongInt;
  WS: WideString;
begin
  F.ReadBuffer(Len, SizeOf(Len));
  SetLength(WS, Len);
  if Len > 0 then
    F.ReadBuffer(WS[1], Length(WS) * SizeOf(WS[1]));
  AData := WS;
end;

procedure ReadBufferDyn(F: TFileStream; out AData: TDynByteArray); overload;
... 

// и так далее для каждого типа данных переменного размера, который вы используете

Тогда чтение-запись свелись бы к:

    F.WriteBuffer(Value.Signature, SizeOf(Value.Signature));
    F.WriteBuffer(Value.Size, SizeOf(Value.Size));
    WriteBufferDyn(F, Value.Comment);
    F.WriteBuffer(Value.CRC, SizeOf(Value.CRC));
...
    F.ReadBuffer(Value.Signature, SizeOf(Value.Signature));
    F.ReadBuffer(Value.Size, SizeOf(Value.Size));
    ReadBufferDyn(F, Value.Comment);
    F.ReadBuffer(Value.CRC, SizeOf(Value.CRC));

Выглядит существенно проще и красивее, не так ли? Иллюстрация силы выделения кода в подпрограммы.

Вообще, конечно же, более правильный код получится при использовании шаблона "декоратор". Суть заключается в создании класса, который реализует методы виде WriteBufferDyn/ReadBufferDyn, выполняя их над потоком, который ему указали. Например:

type
  TStreamDataDecorator = class
  private
    // Управление потоком, с которым мы будем работать 
    FStream: TStream;
    FOwn: Boolean;
    procedure SetStream(const Value: TStream);

    // Вспомогательные методы: добавьте свои на каждый тип динамических данных
    procedure ReadBuffer(var ABuffer; ABufferSize: Integer); overload;
    procedure ReadBuffer(out AStr: String); overload;
    procedure WriteBuffer(const ABuffer; ABufferSize: Integer); overload;
    procedure WriteBuffer(const AStr: WideString); overload;
  public
    // Декоратор
    constructor Create(const AStream: TStream = nil; const AOwn: Boolean = True);
    destructor Destroy; override;

    // Просто для удобства
    property Stream: TStream read FStream write SetStream;
    property Own: Boolean read FOwn write FOwn;

    // Вот ради чего всё делалось: высокоуровневый код
    procedure Write(const AData: TData);
    procedure Read(out AData: TData);
    function EoS: Boolean;
  end;

{ TStreamDataDecorator }

constructor TStreamDataDecorator.Create(const AStream: TStream;
  const AOwn: Boolean);
begin
  inherited Create;
  FStream := AStream;
  FOwn := AOwn;
end;

destructor TStreamDataDecorator.Destroy;
begin
  Stream := nil;
  inherited Destroy;
end;

procedure TStreamDataDecorator.SetStream(const Value: TStream);
begin
  if Assigned(FStream) and FOwn then
    FreeAndNil(FStream);
  FStream := Value;
  FOwn := False;
end;

procedure TStreamDataDecorator.Read(out AData: TData);
begin
  Assert(Assigned(FStream));

  ReadBuffer(AData.Signature, SizeOf(AData.Signature));
  ReadBuffer(AData.Size, SizeOf(AData.Size));
  ReadBuffer(AData.Comment);
  ReadBuffer(AData.CRC, SizeOf(AData.CRC));
end;

procedure TStreamDataDecorator.Write(const AData: TData);
begin
  Assert(Assigned(FStream));

  WriteBuffer(AData.Signature, SizeOf(AData.Signature));
  WriteBuffer(AData.Size, SizeOf(AData.Size));
  WriteBuffer(AData.Comment);
  WriteBuffer(AData.CRC, SizeOf(AData.CRC));
end;

function TStreamDataDecorator.EoS: Boolean;
begin
  Assert(Assigned(FStream));
  Result := (FStream.Position >= FStream.Size);
end;

procedure TStreamDataDecorator.ReadBuffer(var ABuffer; ABufferSize: Integer);
begin
  Assert(Assigned(FStream));

  FStream.ReadBuffer(ABuffer, ABufferSize);
end;

procedure TStreamDataDecorator.ReadBuffer(out AStr: String);
var
  Len: LongInt;
  Str: WideString;
begin
  ReadBuffer(Len, SizeOf(Len));
  SetLength(Str, Len);
  if Len > 0 then
    ReadBuffer(Str[1], Length(Str) * SizeOf(Str[1]));
  AStr := Str;
end;

procedure TStreamDataDecorator.WriteBuffer(const ABuffer; ABufferSize: Integer);
begin
  Assert(Assigned(FStream));

  FStream.WriteBuffer(ABuffer, ABufferSize);
end;

procedure TStreamDataDecorator.WriteBuffer(const AStr: WideString);
var
  Len: LongInt;
begin
  Len := Length(AStr);
  WriteBuffer(Len, SizeOf(Len));
  if Len > 0 then
    WriteBuffer(AStr[1], Length(AStr) * SizeOf(AStr[1]));
end;

В этом примере реализовано 3 вещи: во-первых, мы реализовали хранение ссылки на поток данных, над которым будем выполнять операции. Во-вторых, мы реализовали несколько вспомогательных низкоуровневых операций в секции private. В-третьих, мы реализовали высокоуровневые операции Read и Write в секции public. Тогда сохранение и загрузка сводятся к такому простому коду:

// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TStreamDataDecorator;
  Value: TData;
begin
  Value.Signature := 123;
  Value.Size := SizeOf(Value);
  Value.Comment := 'Example';
  Value.CRC := 0987654321;

  F := TStreamDataDecorator.Create(TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive));
  try
    F.Write(Value);
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TStreamDataDecorator;
  Value: TData;
begin
  F := TStreamDataDecorator.Create(TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite));
  try
    F.Read(Value);
  finally
    FreeAndNil(F);
  end;

  // Здесь Value = значениям из Button1Click
end;

Ну не красота-ли?

Имейте в виду, что именно этот подход вам нужно применять в реальных программах. В примерах ниже я буду применять процедуры вроде WriteBufferDyn/ReadBufferDyn исключительно по соображениям "меньше писать".

Набор (массив) из записей - иерархический набор данных:
```
type
  TPerson = record
    Name: String;
    Age: Integer;
    Salary: Currency;
  end;

  TPersons = array of TPerson;

// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Values: TPersons;
  Index: Integer;
begin
  SetLength(Values, 3);
  for Index := 0 to High(Values) do
  begin
    Values[Index].Name := 'Person #' + IntToStr(Index);
    Values[Index].Age := Random(20) + 20;
    Values[Index].Salary := Random(10) * 5000;
  end;

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    for Index := 0 to High(Values) do
    begin
      WriteBufferDyn(F, Values[Index].Name);
      F.WriteBuffer(Values[Index].Age, SizeOf(Values[Index].Age));
      F.WriteBuffer(Pointer(@Values[Index].Salary)^, SizeOf(Values[Index].Salary));
    end;
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Values: TPersons;
  Value: TPerson;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    while not EoS(F) do
    begin
      ReadBufferDyn(F, Value.Name);
      F.ReadBuffer(Value.Age, SizeOf(Value.Age));
      F.ReadBuffer(Pointer(@Value.Salary)^, SizeOf(Value.Salary));

      SetLength(Values, Length(Values) + 1);
      Values[High(Values)] := Value;
    end;
  finally
    FreeAndNil(F);
  end;

  // Здесь Values тождественно равны исходным данным из Button1Click
end;
```
Для начала хочу сразу же заметить, что странное выражение для поля Salary сделано для обхода бага Delphi. Вообще, там должно стоять просто F.WriteBuffer(Values[Index].Salary, SizeOf(Values[Index].Salary)), но в настоящий момент это выражение даёт ошибку "Variable required", поэтому используется обходной путь: мы берём указатель и разыменовываем его. Вообще говоря, это NOP-операция. А смысл её заключается в потере информации о типе. Это достаточно частый трюк, когда мы хотим запустить свои шаловливые руки под капот языка, минуя информацию типа, но в данном случае он используется для более благих целей: обхода бага компилятора. Вы можете использовать F.WriteBuffer(Values[Index].Salary, SizeOf(Values[Index].Salary)), если ваша версия компилятора это позволяет, или просто выбрать другой тип данных (не Currency).

В любом случае, надо заметить, что достаточно часто при записи/чтении массива записей новички пытаются сделать такую вещь, как запись элемента целиком (F.WriteBuffer(Values[Index], SizeOf(Values[Index]))). Это будет работать для записей фиксированного размера, не содержащих динамические данные (указатели). Ровно как это работает для типизированных файлов. Но если в записях у вас встречаются строки, динамические массивы и другие данные-указатели, то этот подход не будет работать. Собственно, если вы используете типизированные файлы, то компилятор даже не даст вам объявить такой тип данных (file of String, например, или file of Запись, где Запись содержит String). Но суть потоков данных - в прямом доступе, минуя информацию типа. Так что по рукам за это вам никто не даст. Вместо этого код будет просто вылетать или давать неверные результаты. А проблема тут в том, что для динамических данных, поле - это просто указатель. Записывая элемент "как есть" вы запишете в файл значение указателя, но не данные, на которые он указывает. Запись в файл произойдёт нормально, но в файле вы не найдёте своих строк. Чтение из файла тоже пройдёт отлично. Но как только вы попробуете обратиться к прочитанной строке - код вылетит с access violation, потому что указатель строки указывает в космос, на мусор.

Аналогично предыдущим обсуждениям, самый простой способ решения проблемы (но не всегда достаточный) - замена String в записях на ShortString или статический массив символов. Я не буду рассматривать этот вариант, т.к. он сводится к предыдущим примерам с записью данных фиксированного размера.

Вместо этого в примере я показал уже известную технику: запись длины строки вместе с её данными. Это избавляет вас от всех недостатков ShortString/массива символов, но даёт новый недостаток: теперь вы не можете сохранить данные одной строчкой, вам нужно писать их поле-за-полем.

Также по аналогии с предыдущим примером я покажу, как будет выглядеть код, если вы введёте класс-декоратор. Само описание класса я опущу для краткости - оно аналогично (но не тождественно) предыдущему примеру:
```
type
  TStreamPersonDecorator = class
  ...
    procedure Write(const AData: TPerson);
    procedure Read(out AData: TPerson);
  ...
  end;

...

procedure TStreamPersonDecorator.Read(out AData: TPerson);
begin
  Assert(Assigned(FStream));

  ReadBuffer(AData.Name);
  ReadBuffer(AData.Age, SizeOf(AData.Age));
  ReadBuffer(AData.Salary, SizeOf(AData.Salary));
end;

procedure TStreamPersonDecorator.Write(const AData: TPerson);
begin
  Assert(Assigned(FStream));

  WriteBuffer(AData.Name);
  WriteBuffer(AData.Age, SizeOf(AData.Age));
  WriteBuffer(AData.Salary, SizeOf(AData.Salary));
end;

...

// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TStreamPersonDecorator;
  Values: TPersons;
  Index: Integer;
begin
  SetLength(Values, 3);
  for Index := 0 to High(Values) do
  begin
    Values[Index].Name := 'Person #' + IntToStr(Index);
    Values[Index].Age := Random(20) + 20;
    Values[Index].Salary := Random(10) * 5000;
  end;

  F := TStreamPersonDecorator.Create(TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive));
  try
    for Index := 0 to High(Values) do
      F.Write(Values[Index]);
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TStreamPersonDecorator;
  Values: TPersons;
  Value: TPerson;
begin
  F := TStreamPersonDecorator.Create(TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite));
  try
    while not F.EoS do
    begin
      F.Read(Value);

      SetLength(Values, Length(Values) + 1);
      Values[High(Values)] := Value;
    end;
  finally
    FreeAndNil(F);
  end;

  // Здесь Values тождественно равны исходным данным из Button1Click
end;
```
Мы также могли внести методы Read и Write, работающие с массивом из TPerson в класс-декоратор.

Массив из записей внутри записи - составные данные:

type
  TCompose = record
    Signature: LongInt;
    Person: TPerson;
    Count: Integer;
    Related: TPersons;
  end;

  TComposes = array of TCompose;

procedure WriteBufferDyn(F: TFileStream; const APerson: TPerson); overload;
begin
  WriteBufferDyn(F, APerson.Name);
  F.WriteBuffer(APerson.Age, SizeOf(APerson.Age));
  F.WriteBuffer(Pointer(@APerson.Salary)^, SizeOf(APerson.Salary));
end;

procedure WriteBufferDyn(F: TFileStream; const APersons: TPersons); overload;
var
  Len: LongInt;
  Index: Integer;
begin
  Len := Length(APersons);
  F.WriteBuffer(Len, SizeOf(Len));
  for Index := 0 to High(APersons) do
    WriteBufferDyn(F, APersons[Index]);
end;

procedure ReadBufferDyn(F: TFileStream; out APerson: TPerson); overload;
begin
  ReadBufferDyn(F, APerson.Name);
  F.ReadBuffer(APerson.Age, SizeOf(APerson.Age));
  F.ReadBuffer(Pointer(@APerson.Salary)^, SizeOf(APerson.Salary));
end;

procedure ReadBufferDyn(F: TFileStream; out APersons: TPersons); overload;
var
  Len: LongInt;
  Index: Integer;
begin
  F.ReadBuffer(Len, SizeOf(Len));
  SetLength(APersons, Len);
  for Index := 0 to High(APersons) do
    ReadBufferDyn(F, APersons[Index]);
end;

// Сохранение в файл
procedure TForm1.Button1Click(Sender: TObject);
var
  F: TFileStream;
  Values: TComposes;
  Index: Integer;
  PersonIndex: Integer;
begin
  SetLength(Values, 3);
  for Index := 0 to High(Values) do
  begin
    Values[Index].Signature := 123456;
    Values[Index].Person.Name := 'Person #' + IntToStr(Index);
    Values[Index].Person.Age := Random(10) + 20;
    Values[Index].Person.Salary := Random(10) * 5000;
    Values[Index].Count := Random(10);
    SetLength(Values[Index].Related, Random(10));
    for PersonIndex := 0 to High(Values[Index].Related) do
    begin
      Values[Index].Related[PersonIndex].Name := 'Related #' + IntToStr(Index);
      Values[Index].Related[PersonIndex].Age := Random(10) + 20;
      Values[Index].Related[PersonIndex].Salary := Random(10) * 5000;
    end;
  end;

  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmCreate or fmShareExclusive);
  try
    for Index := 0 to High(Values) do
    begin
      F.WriteBuffer(Values[Index].Signature, SizeOf(Values[Index].Signature));
      WriteBufferDyn(F, Values[Index].Person);
      F.WriteBuffer(Values[Index].Count, SizeOf(Values[Index].Count));
      WriteBufferDyn(F, Values[Index].Related);
    end;
  finally
    FreeAndNil(F);
  end;
end;

// Загрузка из файла
procedure TForm1.Button2Click(Sender: TObject);
var
  F: TFileStream;
  Values: TComposes;
  Value: TCompose;
begin
  F := TFileStream.Create(ExtractFilePath(GetModuleName(0)) + 'Test.bin', fmOpenRead or fmShareDenyWrite);
  try
    while not EoS(F) do
    begin
      F.ReadBuffer(Value.Signature, SizeOf(Value.Signature));
      ReadBufferDyn(F, Value.Person);
      F.ReadBuffer(Value.Count, SizeOf(Value.Count));
      ReadBufferDyn(F, Value.Related);

      SetLength(Values, Length(Values) + 1);
      Values[High(Values)] := Value;
    end;
  finally
    FreeAndNil(F);
  end;

  // Здесь Values тождественно равны исходным данным из Button1Click
end;

Как видите - здесь нет никаких проблем, вы просто соединяете воедино техники из предыдущих примеров. Мы используем технику с записью счётчика длины для динамических данных в двух местах: при записи строк и при записи массивов (поле Related).

Кроме того, хотя я мог бы написать весь код в цикле, друг за другом, я всё же выделил новые подпрограммы - исключительно ради удобства. Код теперь выглядит компактно и аккуратно. Он прозрачен и его легко проверить. А если бы я внёс код из подпрограмм в главные циклы, то получилась бы слабочитаемая мешанина кода.

Заметьте, что вы всё ещё должны писать записи по отдельным полям. И если вы меняете объявление записи - вам лучше бы не забыть поменять код, сериализующий и десериализующий запись.

И снова: не забывайте, что это только пример. В реальных программах вам следует посмотреть в сторону класса-декоратора. Я не буду приводить тут пример: он делается по аналогии с предыдущими случаями. Просто добавьте новые методы чтения/записи, вот и всё.

Особенности

Посмотрим теперь на различные конкретные наследники класса TStream и то, что они нам предлагают.

Примечание: не все из нижеперечисленных возможностей существуют во всех версиях Delphi. Если у вас старая версия Delphi, то у вас могут отсутствовать некоторые описываемые классы, свойства или методы. В этом случае вам придётся обходится без них или писать аналоги самостоятельно.

THandleStream

THandleStream предназначен для работы с файлами в смысле операционной системы.

Короче говоря, THandleStream является оболочкой к файлам в стиле ОС. Объект этого типа можно связать с THandle, полученный любым способом - скажем, от CreateFile, CreatePipe и так далее: лишь бы на этот описатель можно было вызывать ReadFile и WriteFile.

Используйте THandleStream в двух случаях:

Функция ОС вернула вам описатель THandle, а код, который вы хотите вызвать, требует TStream. Тогда просто создайте THandleStream, передав в его конструктор описатель от функции ОС, и передайте полученный объект коду. Например:

var
  ReadHandle, WriteHandle: THandle;
  ReadStream, WriteStream: TStream;  
begin
  Win32Check(CreatePipe(@ReadHandle, @WriteHandle, nil, 0));
  try
    ReadStream := THandleStream.Create(ReadHandle);
    WriteStream := THandleStream.Create(WriteHandle);
    try
      ...
      Bitmap.SaveToStream(WriteStream); // Отправляем растровое изображение по pipe
      ...
    finally
      FreeAndNil(WriteStream);
      FreeAndNil(ReadStream);
    end;
  finally
    CloseHandle(WriteHandle);
    CloseHandle(ReadHandle);
  end;
end;

Вы хотите использовать возможность, которую предоставляет функция ОС, но не объект Delphi. См. первый пример в следующем пункте.

Сам THandleStream не имеет ограничений и поддерживает все операции: чтение, запись, позиционирование и изменение размера. Однако нижележащий дескриптор объекта ядра может поддерживать не все операции. К примеру, описатель от файла на диске может быть открыт только для чтения, а описатель pipe не поддерживает позиционирование.

Описатель, которым инициализирован объект, доступен через свойство Handle.

Обратите внимание, что сам THandleStream никогда не закрывает описатель (ему нельзя передать ответственность за него). Поэтому вы должны закрывать описатель вручную или использовать TFileStream (см. ниже).

TFileStream

TFileStream предназначен для работы с файлами на диске.

TFileStream наследуется от THandleStream, так что он получает все возможности своего предка. TFileStream не имеет ограничений на операции и поддерживает конструктор с передачей описателя. Например:

var
  FileHandle: THandle;
  Stream: TFileStream;
begin
  FileHandle := CreateFile('...\Temp.tmp', GENERIC_READ or GENERIC_WRITE, 0, nil, CREATE_ALWAYS, FILE_ATTRIBUTE_TEMPORARY or FILE_FLAG_DELETE_ON_CLOSE, 0);
  Win32Check(FileHandle <> INVALID_FILE_HANDLE);
  Stream := TFileStream.Create(FileHandle);
  try
    ...
  finally
    FreeAndNil(Stream);
    // <- не нужно делать CloseHandle(FileHandle);
  end;
end;

В отличие от THandleStream, TFileStream закрывает открытый описатель файла, вне зависимости от способа его инициализации.

Кроме того, TFileStream поддерживает перегруженный конструктор, позволяющий открывать файлы. У него есть два параметра: (имя файла) и (режим открытия + режим разделения).

Допустимые режимы открытия:

fmCreate - создаёт новый файл. Если такой файл уже есть, он удаляется перед созданием. Файл открывается в режиме записи.
fmOpenRead - открывает файл только для чтения.
fmOpenWrite - открывает файл только для записи.
fmOpenReadWrite - открывает файл для чтения-записи.

Режимы разделения:

fmShareExclusive - запретить совместное использование.
fmShareDenyWrite - запретить другим приложениям запись.
fmShareDenyRead - запретить другим приложениям чтение.
fmShareDenyNone - не вводить ограничения.

Режимы следует соединять друг с другом операцией or.

Примечание: у TFileStream есть вариант конструктора с дополнительным параметром, но этот (третий) параметр существует только для обратной совместимости и сейчас игнорируется. Не следует пытаться передавать в него режим разделения файла.

Флаги разделения используют устаревшую deny-семантику MS-DOS, в отличие от современного API. См. также: взаимодействие флагов режима открытия и разделения.

Типичный пример открытия файла выглядит так:

TFileStream.Create('MyFile.dat', fmOpenRead or fmShareDenyWrite);

А создания файла - так:

TFileStream.Create('MyFile.dat', fmCreate or fmShareExclusive);

При работе с файлами типа логов (для которых необходимы совместное использование или мониторинг) могут использоваться такие вызовы:

TFileStream.Create('MyFile.log', fmOpenRead or fmShareDenyNone);
TFileStream.Create('MyFile.log', fmCreate or fmShareDenyNone);

Далеко не все возможности функций открытия файлов ОС доступны через конструктор TFileStream, но зато он является универсальным для любых платформ. Предпочтительно использовать именно его для доступа к файлам вместо функций ОС. Если же вам нужны какие-либо возможности, недоступные через конструктор TFileStream, то используйте TFileStream, инициализировав его описателем файла от системной функции открытия файлов, как указано в примерах выше.

Если объект TFileStream создавался через конструктор с именем файла, то это имя файла доступно в свойстве FileName, иначе доступно только свойство Handle.

TMemoryStream

TMemoryStream реализует потоковую обёртку к данным в памяти программы. Т.е. к буферу в динамической памяти осуществляется последовательный доступ.

Используйте TMemoryStream, если вам нужен "просто поток" или вам нужен промежуточный буфер-поток.

TMemoryStream имеет конструктор без параметров, который создаёт пустой объект. Для заполнения потока после создания можно использовать обычные методы записи или же специальные методы LoadFromStream (аналог вызова CopyFrom(Stream, 0)) и LoadFromFile.

Также есть методы SaveToStream и SaveToFile.

TMemoryStream не имеет ограничений и поддерживает все операции, включая изменение размера.

TMemoryStream хранит данные в динамической куче процесса, выделяя память по мере необходимости. Он сам автоматически управляет памятью. Реально памяти может быть выделено больше, чем лежит данных в потоке - т.н. "capacity > size". Это стандартная оптимизация для "побайтовых записей".

Дополнительной возможностью TMemoryStream является предоставление свойства Memory, позволяющего обратиться к данным потока напрямую, через указатель, минуя последовательные методы чтения/записи. По этой причине вы можете рассматривать TMemoryStream как "переходник" между TStream и нетипизированным указателем.

Простейший пример использования TMemoryStream (в данном случае - для конвертации строки в TStream):

procedure LoadFromText(const AHandle: THandle; const AText: AnsiString);
var
  Data: TMemoryStream;
begin
  Data := TMemoryStream.Create;
  try
    Data.Write(PAnsiChar(AText)^, Length(AText));
    Data.Position := 0;
    LoadFromStream(AHandle, Data);
  finally
    FreeAndNil(Data);
  end;
end;

Примечание: в данном примере более эффективной была бы другая конструкция. Данный пример по сути копирует данные строки в поток. Но поскольку реально нам нужно здесь только чтение, то можно поступить по другому: создать поток, который будет работать прямо поверх данных строки, без их копирования. Это будет настоящий адаптер. Мы посмотрим на такой пример ниже.

TResourceStream

TResourceStream предназначен для организации последовательного доступа к ресурсам в исполняемых файлах.

TResourceStream похож на TMemoryStream. Он тоже работает с памятью программы (только не с кучей, а с ресурсами), он поддерживает методы SaveToStream и SaveToFile, а также свойство Memory.

Но в отличие от TMemoryStream, TResourceStream поддерживает только методы чтения, но не записи, а также не поддерживает изменение размера. Иными словами, TResourceStream - это read-only.

Собственно для инициализации у TResourceStream есть два варианта конструктора, которые имеют по три параметра: описатель модуля, имя ресурса и тип ресурса. А разница между ними заключается в способе указания имени ресурса (второго параметра): по ID или по имени.

Ну и несколько примеров:

// Пример на использование метода SaveToFile 

// Извлечение своего ресурса в отдельный файл:
procedure ExtractRes(const ResType: PChar; const ResName, ResNewFileName: String);
var
  Res: TResourceStream;
begin
  Res := TResourceStream.Create(HInstance, ResName, ResType);
  try
    Res.SaveToFile(ResNewFileName);
  finally
    FreeAndNil(Res);
  end;
end;

...

ExtractRes('BINFILE', 'MYFILE', 'C:\MyFile.bin');
ExtractRes(RT_RCDATA, 'MYDATA', 'C:\MyData.bin');

// Пример на использование свойства Memory

// Проигрывание MP3 прямо из ресурса, не выгружая его в файл (с использованием BASS)
var
  Res: TResourceStream;
  BkMusic: HSAMPLE;
...
  // Создали обёртку TStream
  Res := TResourceStream.Create(HInstance, 'BKMUSIC', RT_RCDATA);
  // Загружаем напрямую из памяти - нет копирования данных
  BkMusic := BASS_SampleLoad(True, Res.Memory, 0, Res.Size, 1, BASS_SAMPLE_LOOP);
  // Поехали! (С)
  if BkMusic <> 0 then
    BASS_ChannelPlay(BkMusic, False);
...
  if BkMusic <> 0 then
  begin
    BASS_ChannelStop(BkMusic);
    BASS_SampleFree(BkMusic);
    BkMusic := 0;
  end;
  FreeAndNil(Res);
...

TBytesStream

TBytesStream хранит данные потока в массиве байтов.

Используйте TBytesStream как переходник между TBytes и TStream.

Собственно, TBytesStream аналогичен TMemoryStream, только вместо блока памяти в куче он использует TBytes в качестве хранилища для данных. Он также не имеет ограничений на операции, поддерживая чтение, запись, позиционирование и изменение размера. Он поддерживает методы LoadFromStream, LoadFromFile, SaveToStream и SaveToFile, а также свойство Memory.

В отличие от TMemoryStream, у TBytesStream есть конструктор, который принимает переменную типа TBytes - это будут начальные данные потока. При этом не производится копирование данных (используется счётчик ссылок динамического массива). Все операции чтения-записи будут оперировать с исходными данными в оригинальной переменной типа TBytes. Однако если вы измените размер потока (либо явно через Size/SetSize, либо неявно через запись данных в конец потока данных), то поток сделает копию данных и будет работать уже с ней. При этом все будущие изменения в потоке не затронут оригинальной переменной типа TBytes.

Вы также можете передать nil в конструктор, чтобы инициализировать пустой поток. В этом случае он не будет связан с переменной.

Дополнительно TBytesStream вводит свойство Bytes оно работает аналогично свойству Memory, только имеет тип TBytes, а не Pointer. Предупреждение: не пытайтесь использовать Length для определения размера данных. Размер хранилища может быть больше актуального размера ("Capacity > Size"). Используйте свойство Size для определения размера данных.

Простой пример использования TBytesStream как переходника (обратите внимание на усечение данных до их актуального размера, указанного в свойстве Size):

function DecodeBase64(const Input: AnsiString): TBytes;
var
  InStr: TPointerStream;
  OutStr: TBytesStream;
  Len: Integer;
begin
  InStr := TPointerStream.Create(PAnsiChar(Input), Length(Input));
  try
    OutStr := TBytesStream.Create;
    try
      DecodeStream(InStr, OutStr);
      Result := OutStr.Bytes;
      Len := OutStr.Size;
    finally
      FreeAndNil(OutStr);
    end;
  finally
    FreeAndNil(InStr);
  end;
  SetLength(Result, Len);
end;

TBytes является динамическим массивом, т.е. автоуправляемым типом. Явно освобождать его не нужно, заботиться о вопросах владения - тоже.

TStringStream

TStringStream предоставляет последовательный доступ к информации, хранящейся в обычной строке.

Используйте TStringStream для хранения данных в строках. Использование TStringStream даст вам в руки мощные возможности TStream. TStringStream удобен как промежуточный объект, который умеет хранить данные в строке, а также читать и писать их.

По сути, TStringStream является обёрткой к TBytesStream, которая просто конвертирует строку в байты и обратно. У TStringStream есть несколько вариантов конструкторов, которые инициализируют поток по разным типам строк. В Unicode версиях Delphi конструкторы также позволяют вам указывать кодировку для ANSI строк.

Методы чтения-записи TStringStream не затрагивают исходную строку, а всегда работают с копией данных (внутреннее хранилище в виде TBytes).

Ну и, конечно же, TStringStream предоставляет строко-ориентированные свойства и методы. Во-первых, это методы WriteString и ReadString, которые пишут и читают данные из потока в виде строки. При этом кодировка (в Unicode-ных версиях Delphi) контролируется свойством Encoding. И, равно как и предыдущие классы, TStringStream выставляет наружу хранилище в "родном" формате: DataString.

Простой пример использования TStringStream как переходника между строками и TStream:

function EncodeString(const Input: String): String;
var
  InStr, OutStr: TStringStream;
begin
  InStr := TStringStream.Create(Input); // <- использует текущую кодовую страницу ANSI 
  // Можно было так:
  // InStr := TStringStream.Create(Input, CP_UTF8); // <- использует UTF-8
  // или так:
  // InStr := TStringStream.Create(Input, TEncoding.Unicode); // <- использует UTF-16
  try
    OutStr := TStringStream.Create(''); // <- аналогичные замечания
    try
      EncodeStream(InStr, OutStr); // работает с потоками TStream - т.е. двоичными данными
      Result := OutStr.DataString;
    finally
      FreeAndNil(OutStr);
    end;
  finally
    FreeAndNil(InStr);
  end;
end;

Заметьте, что несмотря на наличие методов чтения строк и загрузки/сохранения данных из/в файлы, TStringStream не пригоден для работы с текстовыми файлами. Он не работает с BOM и не позволяет прочитать одну строку (в смысле line) от разделителя до разделителя (он читает только указанное количество символов). По этой причине для работы с текстовыми файлами используют вспомогательный класс - TStringList. Этому классу будет посвящена следующая статья (где и будут показаны методы работы с текстом), а здесь же я только приведу примеры шифрования/расшифровки текстового файла, использующие оба этих класса:

procedure EncodeTextFile(const ASourceFileName, ADestFileName: String);
var
  SourceFile: TStringList;
  SourceData: TStringStream;
  DestFile: TFileStream;
begin
  SourceData := nil;
  try
    // Загрузка данных
    SourceFile := TStringList.Create;
    try
      // "Правильная" загрузка текстового файла с учётом BOM и кодировок
      SourceFile.LoadFromFile(ASourceFileName);

      // Конвертируем строку в TStream
      SourceData := TStringStream.Create(SourceFile.Text, TEncoding.Unicode);
    finally
      FreeAndNil(SourceFile);
    end;

    DestFile := TFileStream.Create(ADestFileName, fmCreate or fmShareExclusive);
    try
      EncodeStream(SourceData, DestFile); // двоичное шифрование
    finally
      FreeAndNil(DestFile);
    end;
  finally
    FreeAndNil(SourceData);
  end;
end;

procedure DecodeToTextFile(const ASourceFileName, ADestFileName: String);
var
  SourceFile: TFileStream;
  DestData: TStringStream;
  DestFile: TStringList;
begin
  SourceFile := TFileStream.Create(ASourceFileName, fmOpenRead or fmShareDenyWrite);
  try
    DestData := TStringStream.Create('', TEncoding.Unicode);
    try
      DecodeStream(SourceFile, DestData); // двоичное дешиврование

      DestFile := TStringList.Create;
      try
        // Конвертируем TStream в строку   
        DestFile.Text := DestData.DataString;

        // "Правильное" сохранение текстового файла с BOM (используем UTF-8)
        DestFile.SaveToFile(ADestFileName, TEncoding.UTF8);
      finally
        FreeAndNil(DestFile);
      end;
    finally
      FreeAndNil(DestData);
    end;
  finally
    FreeAndNil(SourceFile);
  end;
end;

Конечно, на практике такой пример не имеет большого смысла, потому что гораздо проще просто работать с текстовым файлом как с двоичным - обработав его через TFileStream. Но более удачного и простого примера мне сейчас в голову не приходит, а код выше прекрасно показывает пример соединения трёх классов для работы.

TStreamAdapter

Понятие "потока данных" есть не только в Delphi, но и практически в любом другом современном языке. Разумеется, другие языки понятия не имеют, как работать с объектами Delphi, и наоборот: Delphi не знает, как устроены классы и объекты в других языках. К счастью, под Windows у нас есть COM и интерфейсы. С ними умеют работать почти все языки, так что это является де-факто стандартом межязыкового взаимодействия. И, конечно же, не могло быть иначе: для такой популярной концепции как "поток данных" существует свой интерфейс - IStream.

Иными словами, если вам нужно передать куда-то поток данных - вы используете IStream. Если вам кто-то передаёт поток данных, то это будет IStream.

Тут возникает маленькая проблемка: ваши Delphi объекты вообще-то не умеют работать с интерфейсом IStream: они работают с классом TStream. Что же делать?

Для этого в Delphi есть два класса-адаптера, которые конвертируют TStream в IStream и наоборот. При этом они являются тонкими оболочками, которые просто перенаправляют вызовы. Они конвертируют интерфейс, копирования данных потока не происходит: просто вызовы, скажем, класса конвертируются в вызовы интерфейса (и наоборот), работая с данными оригинального потока данных напрямую.

TStreamAdapter предоставляет переходник от TStream к IStream. Он принимает в конструкторе экземпляр TStream и выставляет наружу IStream, который вы можете передать в чужой код.

TStreamAdapter поддерживает те же операции, что и оригинальный поток, который в него завёрнут.

TStreamAdapter может взять на себе ответственность за удаление исходного потока данных, а может оставить её вам. Вот два примера использования TStreamAdapter, иллюстрирующие оба подхода:

var
  Stream: TMemoryStream;
  COMStream: IStream;
begin
  // Готовим поток-источник: это TStream, который приходит от нашего Delphi-кода
  Stream := TMemoryStream.Create;
  try
    Bitmap.SaveToStream(Stream);
    Stream.Position := 0;
    
    // Создаём адаптер. Исходный поток мы должны удалять сами
    COMStream := TStreamAdapter.Create(Stream, soReference);

    // Загрузка растра в Windows Imaging Component 
    FImagingFactory.CreateDecoderFromStream(COMStream, guid_null, WICDecodeMetadataCacheOnDemand, BitmapDecoder));
    ...
  finally
    COMStream := nil;
    FreeAndNil(Stream);
  end; 
end;

var
  Stream: TFileStream;
  COMStream: IStream;
begin
  // Готовим поток-источник: это TStream, который приходит от нашего Delphi-кода
  Stream := TFileStream.Create('My.bmp', fmOpenRead or fmShareDenyWrite);

  // Создаём адаптер. Адаптер удаляет поток, мы не должны его удалять
  COMStream := TStreamAdapter.Create(Stream, soOwned);

  // Загрузка растра в Windows Imaging Component 
  FImagingFactory.CreateDecoderFromStream(COMStream, guid_null, WICDecodeMetadataCacheOnDemand, BitmapDecoder));
  ...
end;

TOleStream

TOleStream представляет собой обратный класс к TStreamAdapter: переходник от IStream к TStream.

Используется он аналогично. Единственная разница - нет вопроса владения, поскольку интерфейсы относятся к автоуправляемым типам.

TOleStream поддерживает те же операции, что и оригинальный поток, который в него завёрнут.

Пример использования TOleStream:

// Открывает файл из композитного OLE-хранилища
function StreamFileRead(const APath: String): TStream;
var
  Strm: IStream;
  StorageToOpen: IStorage;
  FileToOpen: WideString;
begin
  // Пропущены проверки и подготовка
  ...

  // Получаем файл в виде IStream
  if Failed(StorageToOpen.OpenStream(PWideChar(FileToOpen), nil, STGM_READ or STGM_SHARE_EXCLUSIVE, 0, Strm)) then
  begin
    Result := nil;
    Exit;
  end;

  // Конвертируем IStream в TStream. Оригинальный поток (Strm) удалится сам когда надо
  Result := TOleStream.Create(Strm);
  Result.Position := 0;
end;

Прочие потоки

Это далеко не все стандартные потоки, реализованные в Delphi. К примеру, есть ещё TWinSocketStream, TBLOBStream, TZCompressionStream и многие-многие другие. Многие из них являются переходниками, но много классов также предоставляют свою собственную функциональность.

Создание своих классов-потоков

Как бы много в Delphi ни было классов-наследников, всегда найдётся случай, когда вас не устраивают стандартные классы. В этом случае вам нужно реализовывать свой класс-наследник.

К примеру, помните пример для TMemoryStream? Там мы копировали данные строки в поток. Давайте сейчас напишем класс, который позволял бы работать с блоком памяти напрямую, без копирования. Разумеется, такой класс не может поддерживать операцию изменения размера, но чтение, запись и позиционирование - вполне.

Это несложно, если использовать в качестве базового класса TCustomMemoryStream - он уже умеет читать данные из блока памяти, поддерживает позиционирование, но не умеет писать и никак не управляет нижележащим хранилищем. Тогда мы получаем:

type
  // Наш новый класс - наследуем способности TCustomMemoryStream
  TPointerStream = class(TCustomMemoryStream)
  public
    // Нам нужно инициализировать поток данных блоком памяти
    constructor Create(P: Pointer; Size: Integer);
    // И научить его в него писать (а читать уже умеет TCustomMemoryStream)
    function Write(const Buffer; Count: Longint): Longint; override;
  end;

{ TPointerStream }

constructor TPointerStream.Create(P: Pointer; Size: Integer);
begin
  inherited Create;
  SetPointer(P, Size);
end;

function TPointerStream.Write(const Buffer; Count: Integer): Longint;
var
  Pos, EndPos: Int64;
  Mem: Pointer;
  Sz: Int64;
begin
  Result := 0;

  // Есть что писать? 
  Pos := Position;
  if (Pos < 0) or (Count <= 0) then
    Exit;

  // Данные потока
  Mem := Memory;
  Sz := Size;

  // Вычисляем конечную позицию и проверяем, что она в пределах блока памяти
  EndPos := Pos + Count;
  if EndPos > Sz then
    raise EStreamError.Create('Ошибка записи данных в поток');

  // Перенос данных в буфер (в текущую позицию)
  System.Move(Buffer, Pointer(NativeUInt(Mem) + Pos)^, Count);

  // Обновляем текущую позицию потока
  Position := Pos;
  Result := Count;
end;

...

procedure LoadFromText(const AHandle: THandle; const AText: AnsiString);
var
  Data: TPointerStream;
begin
  // Нет копирования данных, оперирует сразу со строкой
  Data := TPointerStream.Create(PAnsiChar(AText), Length(AText));
  try
    LoadFromStream(AHandle, Data); 
  finally
    FreeAndNil(Data);
  end;
end;

Вот список методов, которые вы можете захотеть переопределить в своих классах-наследниках:

(protected) function GetSize: Int64; и procedure SetSize(const NewSize: Int64); - для управление размером хранилища. Если вы не зададите свой GetSize, то реализация по умолчанию будет использовать Seek для поиска конца потока и определения размера (равному текущей позиции в конце потока). SetSize по умолчанию просто ничего не делает.
(public) function Read(var Buffer; Count: Longint): Longint; и function Write(const Buffer; Count: Longint): Longint; для чтения и записи данных. По умолчанию оба метода абстрактные. В любом наследнике вы должны их замещать.
(public) function Seek(const Offset: Int64; Origin: TSeekOrigin): Int64; для перемещения по потоку. Реализация по умолчанию вызывает исключение. Вы должны заместить этот метод, если ваши данные поддерживают позиционирование. Обычно это так. Исключение составляют случаи вроде сетевых сокетов.

Вот и всё. Всего три категории и всего пять методов. Реализуйте их - и у вас будет готовый поток. Все прочие методы и свойства являются переходниками к вышеуказанным. К примеру, метод GetPosition (get-акцессор для свойства Position) реализован как Result := Seek(0, soCurrent);

В общем, как видите, создать свой класс-поток - это очень просто.

Преимущества и недостатки потоков данных

Плюсы:

Де-факто стандарт языка Delphi
Являются основой для других (более высокоуровневых) механизмов
Имеют готовые оболочки для самых типичных случаев ("не надо писать самому" - в отличие от файлов в стиле Pascal)
Гибкость
Стандартная обработка ошибок на исключениях
Поддержка произвольных файлов (нет ограничения на размер)
Нет проблем с многопоточностью
Межъязыковая совместимость (через IStream)
Поддержка Unicode и кодировок при работе с текстовыми данными (но не текстовыми файлами - нет поддержки BOM)
Легко расширяются написанием классов-наследников

Минусы:

Необходимость ручной сериализации данных
Ориентированы на побайтовую обработку, слабо пригодны для работы с текстовыми файлами
Часто неопытные программисты используют Read и Write вместо ReadBuffer и WriteBuffer, не делая проверку результатов. Часто это приводит к некорректному коду без обработки ошибок
Круче кривая обучения: сам TStream не умеет делать ничего. Значит, чтобы делать в программах что-то полезное, нужно изучать многочисленные наследники TStream, чтобы знать кто что умеет и когда что кого нужно применять. К примеру, если вам нужно отправить растр по сети, то вы должны сообразить, что вы можете создать THandleStream для описателя сетевого сокета и использовать его в сочетании с методом SaveToStream объекта растра. Сравните это с файлами в стиле Pascal, где было всего три файловых типа, покрывавших все случаи использования

Вывод: если вы работаете в Delphi и хотите работать с любыми данными, то потоки данных должны быть вашим первым вариантом. Используйте что-то другое, только если это "другое" больше подходит для вашей задачи (к примеру, динамический массив для типизированных данных; также некоторые люди могут рассматривать файлы в стиле Pascal более подходящими для работы с текстовыми данными).

Версия ядра	1
Заголовоный файл	PluginAPI.tlb

Блог GunSmoker-а

Разработка системы плагинов, часть 3: активные плагины

Оглавление

Что хотим

Управление меню

Управление редактором

Разработка системы плагинов в Delphi, часть 2: разработка API

Оглавление

Спецификация

Формализация в коде

Окончательное формирование контракта

IExportPlugin.ExportRTF

Реализация

Разработка системы плагинов в Delphi

Оглавление

Что у нас есть

Что хотим получить

Как пойдём

Основные понятия

Базовый набор правил и соглашений

Структура папок и файлов

Менеджер плагинов

Загрузка одного плагина

Загрузка папки с плагинами

Отключение плагинов

API

Управление заголовочниками

Библиотеки типов

Генерация заголовочников для Delphi и C++ Builder

Генерация заголовочников для Visual Studio C++

Выводы по ведению заголовочных файлов

Начала реализации функциональности

Публичная бета EurekaLog 7

Как попробовать EurekaLog 7

Отличия от EurekaLog 6

EurekaLog 7 в существующих (старых) проектах под EurekaLog 6

Где искать информацию

Участвуй в бета-тесте - выиграй лицензию EurekaLog!

Сериализация - потоки данных

Оглавление

Общие сведения

Общие принципы работы с потоками данных

Обработка ошибок

Правила использования

Практика

Особенности

THandleStream

TFileStream

TMemoryStream

TResourceStream

TBytesStream

TStringStream

TStreamAdapter

TOleStream

Прочие потоки

Создание своих классов-потоков

Преимущества и недостатки потоков данных