]>

# BinaryData

1C++ :: | | Ранее: | Далее:

:: :: _1cpp_guid_ BinaryData

Содержание

- Свойства
  - Кодировка / Encoding
- Методы
  - ЗагрузитьИзФайла / LoadFromFile
  - СохранитьВФайл / SaveToFile
  - ПодключитьсяКФайлу / AttachToFile
  - ЗаписатьСтроку / WriteString
  - ЗаписатьДанные / WriteData
  - ПрочитатьСтроку / ReadString
  - ПрочитатьДанные / ReadData
  - Перейти / Seek
  - Размер / Size
  - УстБлокировку / Lock
  - СнятьБлокировку / Unlock
  - ЗаписатьМПБ / WriteBOM
  - ПрочитатьМПБ / ReadBOM
  - Закрыть / Close
  - Zip
  - Unzip

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

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

# Свойства

## Кодировка / Encoding

> Доступ: чтение и запись.

> Тип: Число.

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

# Методы

## ЗагрузитьИзФайла / 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[пароль]] имя_и_путь_архива путь_к_каталогу_назначения

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