Все потоки, независимо от их типа, имеют одинаковый интерфейс.
Типами потоков являются:
файлы, буферы в оперативной памяти, окна, таблицы,
графики, внешние приложения.
Потоки используются для сохранения, загрузки и визуализации промежуточных
результатов, отладочных данных и окончательных результатов.
Потоки реализуются различными компонентами с интерфейсом ImaStream.
Поток может поддерживать или не поддерживать различные операции
записи и чтения в зависимости от типа потока.
Тип потока задается в момент создания потока,
и определяется классом компонента, который реализует интерфейс ImaStream.
Потоки различных типов отличаются следующими параметрами:
- направленность: запись / чтение;
- формат данных: бинарный / текстовый;
- носитель данных: файл / буфер / приложение.
HRESULT Open ()
Функция открывает поток, если он еще не был открыт, и
увеличивает внутренний счетчик числа открытий на единицу.
Первоначально значение этого счетчика равно нулю.
Использовать эту функцию не обязательно.
Однако для некоторых типов потоков (например, файлов)
имеет смысл открыть поток один раз перед многократным обращением
к функциям ввода-вывода, а по завершении работы закрыть поток.
Тогда поток не будет открываться и закрываться при чтении/записи
каждой порции данных, что повысит эффективность операции.
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_IOPERM если при открытии произошла ошибка
HRESULT Close ()
Функция уменьшает внутренний счетчик числа
открытий на единицу и, если он равен нулю, закрывает поток.
Возвращаемое значение:
MA_NOERROR всегда
HRESULT Flush ()
Функция принудительно выводит в поток содержимое внутреннего буфера
(если таковой определён для данного типа потоков).
Возвращаемое значение:
MA_NOERROR всегда
Следующие функции предназначены для работы с опциями ввода-вывода
HRESULT GetOptions([out,retval] maStreamOptions* opt)
Функция возвращает текущие опции ввода-вывода.
Параметры:
opt указатель на возвращаемое значение
Возвращаемое значение:
MA_NOERROR Всегда
HRESULT SetOptions([in] maStreamOptions opt)
Функция устанавливает текущие опции ввода-вывода.
Параметры:
opt новые опции ввода-вывода
Возвращаемое значение:
MA_NOERROR Всегда
HRESULT PushOptions([in] maStreamOptions opt)
Функция сохраняет текущие опции ввода-вывода во внутреннем стеке и затем заменяет текущие опции на opt.
Параметры:
opt новые опции ввода-вывода
Возвращаемое значение:
MA_NOERROR Всегда
HRESULT PopOptions()
Функция восстанавливает предыдущие опции ввода-вывода.
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_NOTFOUND если внутренний стек пуст
HRESULT WriteStr ([in,string] maString value)
HRESULT WriteLong([in] int value)
HRESULT WriteDouble([in] double value)
Функции выводят простое значение в текстовый поток.
Формат вывода задается опциями потока.
Если поток не открыт, то он открывается, и по завершении вывода закрывается.
Параметры:
value записываемое значение
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_IOPERM если запись в поток запрещена
HRESULT ReadStr ([out,retval,string] maString* value)
HRESULT ReadLong([out,retval] int* value)
HRESULT ReadDouble([out,retval] double* value)
Функции считывают простое значение из текстового потока.
Если поток не открыт, то он открывается,
и по завершении ввода закрывается. Функция ReadStr выделяет память под строку сама.
Параметры:
value указатель на читаемое значение
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_IOPERM если чтение из потока запрещено
HRESULT WriteBlock ([in] void* ptr, [in] int length)
Функция записывает блок данных заданной длины.
Только для бинарных потоков.
Если поток не открыт, то он открывается, и по завершении ввода/вывода
закрывается.
Параметры:
ptr указатель на записываемые данные
length длина записываемых данных
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_IOPERM если запись в поток запрещена
HRESULT ReadBlock ([in] void* ptr, [in] int length)
Функция счикывает блок данных заданной длины.
Только для бинарных потоков.
Если поток не открыт, то он открывается, и по завершении ввода/вывода
закрывается.
Параметры:
ptr указатель на считываемые данные
length длина считываемых данных
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_IOPERM если чтение из потока запрещено
HRESULT WriteComponent([in] IPersist* comp)
Функция записи компонента.
Если поток не открыт, то он открывается, и по завершении ввода/вывода
закрывается.
Параметры:
comp указатель на компонент
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_BAD_PARAM если comp==NULL
MA_ERR_IOPERM если запись в поток запрещена
MA_ERR_NOINTERFACE если компонент не имеет интерфейса ImaSupportsStreaming
HRESULT ReadComponent([in,out] IPersist** comp)
Функции чтения компонента.
Если при вызове функции
*comp==0
, то создается компонент с
CLSID, считанным из потока.
Если
*comp!=0
, то считанный из потока CLSID сравнивается с CLSID компонента *comp,
и при совпадении данные считываются в компонент *comp, а при несовпадении — возвращается
код ошибки MA_ERR_BAD_CLSID и позиция в файле остается той же, что и до вызова.
Если поток не открыт, то он открывается, и по завершении ввода/вывода
закрывается.
Параметры:
comp указатель на считываемый компонент
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_BAD_PARAM если comp==NULL
MA_ERR_IOPERM если чтение из потока запрещено
MA_ERR_NOINTERFACE если компонент не имеет интерфейса ImaSupportsStreaming
MA_ERR_BAD_CLSID если считанный из потока CLSID не существыет или не равен CLSID компонента *comp
HRESULT NewLine()
HRESULT NewField()
Переход к новой строке и вставка разделителя значений соответственно.
Что именно будет записано в поток, определяется
опциями ввода-вывода.
Если поток не текстовый, то вызовы игнорируются.
Возвращаемое значение:
MA_NOERROR при отсутствии ошибок
MA_ERR_IOPERM если запись в поток запрещена