.. Автор: Дмитрий Ощепков aka DmitrO, mailto: dmitro@russian.ru

.. include:: commonchm.txt

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Описание интерфейса поставщиков данных табличного поля
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
..	<chminfo>
		<insert nodes="//common/maininfo/*"/>
		<alinks>_1cpp_data_provider_sdk_</alinks>
	</chminfo>

.. contents:: Содержание
	:backlinks: none


Настоящее описание является основной документацией для разработки *поставщиков данных*.
Поставщики данных - это объекты, работающие под управлением элемента управления (ЭУ) - объекта ТабличноеПоле.

Поставщик данных должен реализовать интерфейсы двух абстрактных классов:

	- CDataProvider_;
	- CV7DataProvider_.

Через эти интерфейсы поставщик должен передавать *объекты строк данных*. Эти объекты должны реализовать интерфейсы
двух абстрактных классов:

	- CDataRow_;
	- CV7DataRow_.

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

Классы CDataProvider_ и CDataRow_ описаны в заголовочном файле DataProvider.h. Они являются общими и могут применяться
вне среды 1C (V7).

Классы CV7DataProvider_ и CV7DataRow_ описаны в заголовочном файле V7DataProvider.h. Они являются расширением интерфейса
поставщиков данных для более эффективной и гибкой работы в среде 1C (V7).


#####################################################################
CDataProvider
#####################################################################
Базовый класс для всех поставщиков данных. Содержит интерфейсы, через которые ЭУ управляет поставщиком данных.
Каждый поставщик данных должен реализовать `Интерфейс запроса и получения строк`_.

Интерфейс общего назначения
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

Собраны функции общего назначения.

GetControl
---------------------------------------------------------------------
	**Синтаксис:** ``HWND GetControl() const;``

	**Возвращает:** дескриптор ЭУ, если NULL - поставщик не подключен к ЭУ.

	**Описание:** позволяет получить дескриптор ЭУ, подключенного в данный момент к поставщику данных.

SetControl
---------------------------------------------------------------------
	**Синтаксис:** ``void SetControl(HWND hControl);``

	**Описание:** позволяет установить дескриптор ЭУ, подключая таким образом поставщика данных к ЭУ. Эту процедуру
	вызывает сам ЭУ.

ResetData
---------------------------------------------------------------------
	**Синтаксис:** ``void ResetData(CDataRow* pDataRow = NULL);``

	**Параметры:**

		- pDataRow - указатель на строку данных, которую требуется сделать текущей при инициализации.

	**Описание:** позволяет инициализировать заполнение ЭУ. Имеет эффект только в том случае, когда поставщик данных
	подключен к ЭУ.

SetCurrentRow
---------------------------------------------------------------------
	**Синтаксис:** ``void SetCurrentRow(CDataRow* pDataRow);``

	**Параметры:**

		- pDataRow - указатель на строку данных, которую требуется сделать текущей.

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

OnDetach
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void OnDetach();``

	**Описание:** вызвается после отключения поставщика данных от ЭУ.

OnAttach
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void OnAttach();``

	**Описание:** вызвается после подключения поставщика данных к ЭУ.

Интерфейс запроса и получения строк
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

Основной интерфейс поставщика данных.

Реализация обязательна.

QueryRows
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void QueryRows(CDataRow* pRowFrom, int nRowsCount, int nPageSizeHint) = 0;``

	**Параметры:**

		- pRowFrom - строка данных, от которой необходимо получить строки. Может быть равен NULL, это означает, что
		  строки запрашиваются с крайнего положения: с начала или с конца (см. параметр nRowsCount);
		- nRowsCount - запрашиваемое количество строк. Знак указывает направление.
		  Если параметр больше нуля - запрашиваются следующие строки (вниз).
		  Если параметр меньше нуля - запрашиваются предыдущие строки (вверх);
		- nPageSizeHint - размер страницы. Всегда положительное число, которое передается элементом управления
		  для подсказки поставщику, чтобы тот мог оптимизировать свое поведение.

	**Описание:** запрашивает строки у поставщика данных. После вызова метода всегда будет один или несколько вызов
	Fetch_ для собственно получения строк элементом управления.

Fetch
---------------------------------------------------------------------
	**Синтаксис:** ``virtual CDataRow* Fetch() = 0;``

	**Возвращает:** указатель на строку данных.

	**Описание:** возвращает запрошенные методом QueryRows_ строки данных. Если возвращается NULL - это означает,
	что все строки последнего запроса были выбраны. Поставщик данных должен вернуть столько строк,
	сколько запрошено в параметре nRowsCount в предыдущем вызове метода QueryRows_, иначе ЭУ считает, что в
	данном направлении достигнут конец выборки строк, и последующие запросы в этом направлении выполнять не будет.

	**Замечание:** поставщик данных не должен следить за освобождением памяти объекта строки данных. После того,
	как строка передана поставщику данных ЭУ, освобождение этого объекта - ответственность ЭУ.

RefreshRow
---------------------------------------------------------------------
	**Синтаксис:** ``virtual BOOL RefreshRow(CDataRow* pRowFrom) = 0;``

	**Параметры:**

		- pRowFrom - указатель на строку данных, данные которой необходимо обновить.

	**Возвращает:** результат успешности обновления данных строки.

	**Описание:** поставщик данных должен обновить данные строки.

CompareRows
---------------------------------------------------------------------
	**Синтаксис:** ``virtual BOOL CompareRows(CDataRow* pRow1, CDataRow* pRow2) const = 0;``

	**Параметры:**

		- pRow1 - указатель на одну строку данных;
		- pRow2 - указатель на другую строку данных.

	**Возвращает:** TRUE, если эти два объекта представляют одну и ту же строку, иначе FALSE.

	**Описание:** поставщик данных должен сравнить объекты строк. Дело в том, что при работе ЭУ может сохранять
	объекты строк, но в некоторых ситуациях он может запросить те же строки заново. Для того, чтобы ЭУ знал, что
	новый полученный объект представляет ту же строку - необходим этот метод.

GetLastError
---------------------------------------------------------------------
	**Синтаксис:** ``virtual LPCSTR GetLastError();``

	**Возвращает:** указатель на строку - описание ошибки в работе поставщика данных.

	**Описание:** метод нужен для диагностики неправильной работы поставщика данных. Если метод возвращает не NULL,
	то ЭУ будет визуально сообщать об ошибке текстом полученным при вызове этого метода.

GetRowCount
---------------------------------------------------------------------
	**Синтаксис:** ``virtual BOOL GetRowCount(UINT* pCount);``

	**Параметры:**

		- pCount - указатель на переменную, принимающую количество строк в наборе данных.

	**Возвращает:** поддерживает ли поставщик данных определение относительного положения записи.

	**Описание:** этим методом запрашивается общее количество строк в наборе данных и размер набора данных. Если метод
	возвращает TRUE - значит, поставщик поддерживает определение относительного положения записи во всем наборе данных,
	и по указателю pCount записано общее количество строк в наборе, иначе поставщик не поддерживает определение
	относительное положения записи в наборе данных.
	См. также GetRowIndex_.

Интерфейс управления составом полей
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

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

Реализация не обязательна.

QueryField
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void QueryField(LPCSTR szFieldName);``

	**Параметры:**

		- szFieldName - имя поля данных.

	**Описание:** метод вызывается, когда элементу управления требуется отображать содержимое поля с именем szFieldName.

ReleaseField
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void ReleaseField(LPCSTR szFieldName);``

	**Параметры:**

		- szFieldName - имя поля данных.

	**Описание:** метод вызывается, когда элементу управления больше не требуется отображать содержимое поля с именем
	szFieldName.

OnFieldsChanged
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void OnFieldsChanged();``

	**Описание:** этот метод должен вызываться поставщиком данных внутренне при изменении состава полей данных.
	Стандартные действия этого метода - команда элементу управления о том, что состав полей изменился.

Интерфейс быстрого поиска
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

Используется для обслуживания *быстрого поиска* в наборе данных отображаемом поставщиком данных.

Реализация не обязательна.

GetQuickSearchType
---------------------------------------------------------------------
	**Синтаксис:** ``virtual DataType GetQuickSearchType(LPCSTR szFieldName);``

	**Параметры:**

		- szFieldName - имя поля данных.

	**Возвращает:** тип данных для ввода образца для поиска по полю szFieldName.

	**Описание:** метод вызывается, когда элементу управления требуется определить - поддерживается ли поставщиком данных
	быстрый поиск по полю szFieldName. Если возвращается dtUndefined - по этому полю быстрый поиск не поддерживается,
	иначе возвращяемое значение определяет тип данных для ввода образца для поиска по полю szFieldName.

	**Замечание:** в настоящий момент поддерживается только dtText.

QuickSearch
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void QuickSearch(stQuickSearchPattern& QSPattern);``

	**Параметры:**

		- QSPattern - ссылка на структуру stQuickSearchPattern_ - с данными образца для поиска.

	**Описание:** поставщик данных должен выполнить быстрый поиск по переданному образцу. Результатом поиска должна
	быть активизация строки (SetCurrentRow_). А также возможно изменение данных структуры stQuickSearchPattern_.

Структуры даных
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

stQuickSearchPattern
---------------------------------------------------------------------
	**Синтаксис:** 

	::

		struct stQuickSearchPattern
		{
			LPCSTR szFieldName;
			DataType dataType;
			union
			{
				CString* pTextData; //for text fields;
			};
		};

	:szFieldName:

		Имя поля данных, по которому требуется выполнить поиск.

	:dataType:

		Тип данных образца для поиска.

	:pTextData:

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

	**Описание:** используется для передачи образца данных для выполнения быстрого поиска поставщиком данных.

Перечисления
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

DataType
---------------------------------------------------------------------
	**Синтаксис:** 

	::

		enum DataType
		{
			dtUndefined,
			dtText,
			dtNumeric,
			dtDate,
			dtFalse,
			dtTrue,
		};

	**Описание:** используется для обозначения типа данных поля поставщика данных:

		- dtUndefined: тип не определен;
		- dtText: строка (текст);
		- dtNumeric: число;
		- dtDate: дата;
		- dtFalse: булево значение Ложь;
		- dtTrue: булево значение Истина.

#####################################################################
CDataRow
#####################################################################
Базовый класс для класса строки данных (записи).

Интерфейс строки данных
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

GetFieldCount
---------------------------------------------------------------------
	**Синтаксис:** ``virtual int GetFieldCount() = 0;``

	**Возвращает:** количество полей.

	**Описание:** позволяет определить количество полей.

GetFieldIndexOf
---------------------------------------------------------------------
	**Синтаксис:** ``virtual int GetFieldIndexOf(LPCSTR szFieldName) = 0;``

	**Параметры:**

		- szFieldName - имя поля данных.

	**Возвращает:** индекс поля данных.

	**Описание:** позволяет определить индекс поля по имени. Если поля с таким именем нет, должно возвращаться
	значение -1.

GetFieldName
---------------------------------------------------------------------
	**Синтаксис:** ``virtual LPCSTR GetFieldName(int nIndex) = 0;``

	**Параметры:**

		- nIndex - индекс поля данных.

	**Возвращает:** указатель на строку с именем поля данных.

	**Описание:** позволяет определить имя поля по индексу.

GetFieldType
---------------------------------------------------------------------
	**Синтаксис:** ``virtual DataType GetFieldType(int nIndex);``

	**Параметры:**

		- nIndex - индекс поля данных.

	**Возвращает:** тип поля данных.

	**Описание:** позволяет определить тип поля данных. Используется элементом управления, для общепринятого
	отображения различных типов данных.

FormatField
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void FormatField(int nIndex, CString& strValue) = 0;``

	**Параметры:**

		- nIndex - индекс поля данных;
		- strValue - строка для форматирования значения поля данных.

	**Описание:** форматирует значение поля данных. strValue - строка, в которой должно произойти форматирование.

GetRowIndex
---------------------------------------------------------------------
	**Синтаксис:** ``virtual UINT GetRowIndex();``

	**Возвращает:** индекс строки данных (записи) в наборе данных.

	**Описание:** позволяет получить индекс строки (записи) для определения относительного положения строки в наборе
	данных. Метод вызывается только в том случае, если поставщик поддерживает этот функционал.
	См. также GetRowCount_.

#####################################################################
CV7DataProvider
#####################################################################
Базовый класс для поставщика данных. Этот класс является расширением поставщиков данных для среды 1CV7.

Интерфейс
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

GetV7DataRow
---------------------------------------------------------------------
	**Синтаксис:** ``virtual CV7DataRow* GetV7DataRow(CDataRow* pDataRow) const = 0;``

	**Параметры:**

		- pDataRow - указатель на строку данных (получен от поставщика данных).

	**Возвращает:** указатель на строку данных типа CV7DataRow_.
	
	**Описание:** Этот метод является вспомогательным. Служит для преобразования CDataRow* в CV7DataRow*. Дело в том,
	что сам ЭУ не может выполнить такое преобразование безопасно, или для этого придется применять динамическое
	преобразование по RTTI - это неоправдано медленно для каждой строки. А поставщик данных может выполнить
	такое преобразование статически. (фактически нужно выполнить upcast и downcast)

GetRowValue
---------------------------------------------------------------------
	**Синтаксис:** ``virtual void GetRowValue(CDataRow* pDataRow, CValue& value) const;``

	**Параметры:**

		- pDataRow - указатель на строку данных (получен от поставщика данных).
		- value - [out] объект для приема результата.

	**Описание:** с помощью этого метода ЭУ получает в параметре value значение, представляющее переданную параметром
	pDataRow строку данных.
	
	**Примечание:** метод используется для реализации свойства табличного поля ТекущаяСтрока по чтению. Поставщик должен
	реализовать этот метод, если требуется этот функционал.

BuildRowByValue
---------------------------------------------------------------------
	**Синтаксис:** ``virtual CDataRow* BuildRowByValue(const CValue& value);``

	**Параметры:**

		- value - значение представляющее строку данных.

	**Возвращает:** указатель на строку данных.

	**Описание:** с помощью этого метода ЭУ пытается получить от поставщика данных новый экземпляр строки данных по
	значению переданному параметром value. Значение параметра должно представлять строку данных. Объект строки
	данных, указатель на который возвращается, должен быть временным и будет освобожден элементом управления, после
	использования его для установки текущей строки.
	
	**Примечание:** метод используется для реализации свойства табличного поля ТекущаяСтрока по записи.

#####################################################################
CV7DataRow
#####################################################################
Базовый класс для класса строки данных (записи).  Этот класс является расширением класса строки данных для среды 1CV7.

Интерфейс
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

GetValue
---------------------------------------------------------------------
	**Синтаксис:** ``virtual const CValue& GetValue(int nIndex) const = 0;``

	**Параметры:**

		- nIndex - индекс поля данных.

	**Возвращает:** ссылку на объект значения поля данных.

	**Описание:** позволяет элементу управления получить значение поля данных.

FormatValue
---------------------------------------------------------------------
	**Синтаксис:** ``static void FormatValue(const CValue& Value, CString& strValue);``

	**Параметры:**

		- Value - значение для форматирования;
		- strValue - [out] результат форматирования.

	**Описание:** вспомогательная процедура, которая форматирует значение Value по общепринятым в 1CV7
	правилам форматирования значений для отображения в таблицах.
