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

.. include:: commonchm.txt

#####################################################################
BinaryData
#####################################################################
..	<chminfo>
		<insert nodes="//common/maininfo/*"/>
		<alinks>_1cpp_guid_</alinks>
		<klinks>
			BinaryData
		</klinks>
	</chminfo>

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

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

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

Свойства
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

Кодировка / Encoding
------------------------------------------------
	**Доступ:** чтение и запись.
	
	**Тип:** Число.
	
	**Описание:** Содержит текущую кодировку, в которой будут происходить чтение и запись строк.
		- 1 - ANSI (по умолчанию);
		- 2 - OEM;
		- 3 - UTF-16(LE);
		- 4 - UTF-8.

Методы
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

ЗагрузитьИзФайла / LoadFromFile
------------------------------------------------
	**Синтаксис:** ЗагрузитьИзФайла(ИмяФайла, [ФлагСжатия])

	**Параметры:**
		- **ИмяФайла** - тип: Строка. Имя файла - источника данных;
		- **ФлагСжатия** - тип: Число. 0 - загрузка данными как есть, 1 - при загрузке данные будут сжаты
		  внутренним архиватором 1С (zip), после этого объект будет содержать данные файла в сжатом виде. По умолчанию 0.
	
	**Возвращает:** тип: Число. 1 - удачно, 0 - неудачно.
	
	**Описание:** загружает объект данными из файла. Если объект был подключен к файлу, данные загружаются в файл.
	Текущие данные объекта очищаются.
	
СохранитьВФайл / SaveToFile
------------------------------------------------
	**Синтаксис:** СохранитьВФайл(ИмяФайла, [ФлагСжатия])

	**Параметры:**
		- **ИмяФайла** - тип: Строка. Имя файла - приемника данных;
		- **ФлагСжатия** - тип: Число. 0 - выгрузка данных как есть, 1 - при выгрузке данные будут расжаты внутренним
		  архиватором 1С (zip), и файл приемник будет содержать исходные данные. По умолчанию 0.
	
	**Возвращает:** тип: Число. 1 - удачно, 0 - неудачно.
	
	**Описание:** выгружает данные объекта в файл.

ПодключитьсяКФайлу / AttachToFile
------------------------------------------------
	**Синтаксис:** ПодключитьсяКФайлу(ИмяФайла, [РежимРазделения], [РежимДоступа])

	**Параметры:**
		- **ИмяФайла** - тип: Строка. Имя файла, к которому необходимо подключиться;
		- **РежимРазделения** - тип: Число. Режим открытия файла:

			- 0 - эксклюзивно (по умолчанию);
			- 1 - разделенно, другим процессам разрешены чтение и запись;
			- 2 - разделенно, другим процессам разрешено только чтение;
			- 3 - разделенно, другим процессам разрешена только запись.

		- **РежимДоступа** - тип: Число. Режим открытия файла, желаемый доступ:

			- 0 - чтение и запись (по умолчанию);
			- 1 - только чтение;
			- 2 - только запись.
	
	**Возвращает:** тип: Число. 1 - удачно, 0 - неудачно.
	
	**Описание:** подключает объект к файлу. После этого объект хранит свои данные в файле. Если объект
	до этого содержал данные в памяти - они теряются. Если он работал с файлом - старый файл освобождается.
	Если файла не существует - он создается с нулевой длиной.

ЗаписатьСтроку / WriteString
------------------------------------------------
	**Синтаксис:** ЗаписатьСтроку(Данные, [Режим])

	**Параметры:**
		- **Данные** - тип: Строка. Строка данных для записи;
		- **Режим** - тип: Число. режим записи; 0 - запись строки с добавлением символов конца строки CR LF.
		  1 - запись строки как есть (без терминатора). По умолчанию 0.
	
	**Описание:** записывает строку в данные объекта. Строка будет перекодирована и записана в файл
	в соответствии со свойством `Кодировка / Encoding`_.

ЗаписатьДанные / WriteData
------------------------------------------------
	**Синтаксис:** ЗаписатьДанные(Данные, [Режим])

	**Параметры:**
		- **Данные** - тип: Число. Число, которое необходимо записать;
		- **Режим** - тип: Число. Режим записи:

			- 0 - записывается число в 1 байт (по умолчанию);
			- 1 - записывается число в 2 байта;
			- 2 - записывается число в 4 байта.
	
	**Описание:** записывает переданное число в данные объекта. Число может быть только целым, записывается
	младшими байтами вперед.

ПрочитатьСтроку / ReadString
------------------------------------------------
	**Синтаксис:** ПрочитатьСтроку(Данные, [Режим])

	**Параметры:**
		- **Данные** - тип: Строка. Строка для приема прочитанных данных;
		- **Режим** - тип: Число. Режим чтения или длина. 0 - чтение строки, с терминатором CR LF, при этом
		  чтение может завершиться, если встретится байт со значением 0; текущая позиция внутреннего указателя
		  будет всегда за терминатором; также может произойти чтение до конца данных, при этом в Данные будет
		  прочитанная строка, и функция вернет 1 (0 функция вернет при следующем вызове). Иначе - чтение строки
		  указанной длины. Если данных недостаточно или на этой длине встречается байт со значением 0 - происходит
		  исключение. В этом режиме невозможно чтение в кодировке UTF-8. По умолчанию 0.
	
	**Возвращает:** тип: Число. 1 - строка прочитана, 0 - достигнут конец файла.

	**Описание:** читает строку из данных объекта. Строка будет прочитана из файла и перекодирована
	в соответствии со свойством `Кодировка / Encoding`_.

ПрочитатьДанные / ReadData
------------------------------------------------
	**Синтаксис:** ПрочитатьДанные(Данные, [Режим])

	**Параметры:**
		- **Данные** - тип: Число. Число, для приема прочитанных данных;
		- **Режим** - тип: Число. Режим чтения:

			- 0 - читается число в 1 байт (по умолчанию);
			- 1 - читается число в 2 байта;
			- 2 - читается число в 4 байта.

	**Описание:** читает число из данных объекта. Если данных недостаточно для чтения числа - происходит исключение.

Перейти / Seek
------------------------------------------------
	**Синтаксис:** Перейти(Перемещение, [Режим])

	**Параметры:**
		- **Перемещение** - тип: Число. Количество байт, на которое нужно переместить указатель.
		- **Режим** - тип: Число. Режим перемещения:

			- 0 - относительно начала;
			- 1 - относительно текущей позиции (по умолчанию);
			- 2 - относительно конца.

	**Возвращает:** тип: Число. Новая текущая позиция внутреннего указателя.

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

Размер / Size
------------------------------------------------
	**Синтаксис:** Размер(НовыйРазмер)

	**Параметры:**
		- **НовыйРазмер** - тип Число. Новый размер в байтах. По умолчанию пустое значение.

	**Возвращает:** тип: Число. Размер в байтах.

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

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

УстБлокировку / Lock
------------------------------------------------
	**Синтаксис:** УстБлокировку(Смещение, Длина, [Таймаут])

	**Параметры:**
		- **Смещение** - тип Число. Смещение блокируемого диапазона относительно начала файла в байтах;
		- **Длина** - тип Число. Длина блокируемого диапазона в байтах;
		- **Таймаут** - тип Число. Таймаут для установки блокировки в миллисекундах, по умолчанию 0.

	**Возвращает:** тип: Число. 1 - удачно (блокировка установлена), 0 - неудачно (блокировку установить не удалось).

	**Описание:** устанавливает блокировку на указанный диапазон в файле (когда объект работает с памятью -
	смысла не имеет). Блокируемые участки не должны пересекаться. Блокирование за концом файла не является ошибкой.

СнятьБлокировку / Unlock
------------------------------------------------
	**Синтаксис:** УстБлокировку(Смещение, Длина, [Таймаут])

	**Параметры:**
		- **Смещение** - тип Число. Смещение блокируемого диапазона относительно начала файла в байтах;
		- **Длина** - тип Число. Длина блокируемого диапазона в байтах;

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

ЗаписатьМПБ / WriteBOM
------------------------------------------------
	**Синтаксис:** ЗаписатьМПБ()

	**Описание:** записывает в файл метку порядка байтов (byte order mark). В зависимости от текущей кодировки:
		- UTF-16 {0xFF, 0xFE};
		- UTF-8 {0xEF, 0xBB, 0xBF};
		- для остальных ничего не происходит.

ПрочитатьМПБ / ReadBOM
------------------------------------------------
	**Синтаксис:** ПрочитатьМПБ()

	**Описание:** читает из файла метку порядка байтов, и определяет по ней кодировку, устанавливая свойство
	`Кодировка / Encoding`_.
	Кодировка может быть определена только для UTF-16 и UTF-8, в этом случае внутренний указатель будет установлен
	сразу за МПБ, если же прочитанные байты не совпадают ни с тем, ни с другим значением МПБ - свойство
	`Кодировка / Encoding`_ не изменяется и внутренний указатель возвращается в положение до вызова метода.

Закрыть / Close
------------------------------------------------
	**Синтаксис:** Закрыть()

	**Описание:** переводит объект в режим отсутствия данных. Если он работал с памятью - данные теряются,
	если с файлом - файл освобождается. Действия этого метода неявно выполняются при разрушении объекта.

Zip
------------------------------------------------
	**Синтаксис:** Zip(Команда)

	**Параметры:**
		- **Команда** - тип Строка. Командная строка архиватору. Формат командной строки::

			[-s[пароль]] имя_и_путь_создаваемого_архива имя_и_путь_архивируемого_файла(ов)


	**Описание:** сжимает файлы внутренним архиватором. Метод не влияет на состояние и на данные объекта.

Unzip
------------------------------------------------
	**Синтаксис:** Unzip(Команда)

	**Параметры:**
		- **Команда** - тип Строка. Командная строка архиватору. Формат командной строки::

			[-s[пароль]] имя_и_путь_архива путь_к_каталогу_назначения

	**Описание:** разжимает файлы внутренним архиватором. Метод не влияет на состояние и на данные объекта.
