libcasio/docs/user/file.rst

File management
===============

libcasio manages the file formats through a file API where you can open and
decode a file, and export data into a file. A file is primarily represented
by its type and platform:

.. c:type:: casio_filetype_t

	An enumeration defining various file types that file formats libcasio
	can read and write can represent. The values in this enumeration are
	defined as flags so that such a value can also represent multiple
	file types with no ambiguity.

	.. c:macro:: casio_filetype_addin

		An add-in, i.e. a binary application which executes natively onto
		the calculator from the storage filesystem(s). The platform cannot
		be :c:macro:`casio_filefor_none` for this type.

	.. c:macro:: casio_filetype_add_in

		An alias for :c:macro:`casio_filetype_addin`.

	.. c:macro:: casio_filetype_mcs

		A main memory backup, see :ref:`mcs` for more details about
		what a main memory is.

	.. c:macro:: casio_filetype_eact

		An e-activity, i.e. rich document for storing courses for example.

	.. c:macro:: casio_filetype_e_activity

		An alias for :c:macro:`casio_filetype_eact`.

	.. c:macro:: casio_filetype_eactivity

		An alias for :c:macro:`casio_filetype_eact`.

	.. c:macro:: casio_filetype_picture

		A picture, e.g. ``*.g3p`` files.

	.. c:macro:: casio_filetype_pict

		An alias for :c:macro:`casio_filetype_picture`.

	.. c:macro:: casio_filetype_lang

		A language file, which contains message translations with IDs,
		e.g. ``*.g1l`` or ``*.g3l`` files.

	.. c:macro:: casio_filetype_fkey

		A function key file, which contains function key pictures with IDs
		in the same fashion than language files, e.g. ``*.g1n`` files.

	.. c:macro:: casio_filetype_storage

		A storage filesystem backup, typically ``*.g1s`` files.

.. c:type:: casio_filefor_t

	An enumeration defining various platforms for which the file formats
	libcasio can read and write can be made for. The values in this enumeration
	are defined as flags so that such a value can also represent multiple
	file platforms with no ambiguity.

	.. c:macro:: casio_filefor_none

		No platform in particular; this value always evaluates as zero, so
		that any other value in this enumeration can make it precise.

	.. c:macro:: casio_filefor_fx

		The fx-9860G family of calculators, OS 1.x and OS 2.x.

	.. c:macro:: casio_filefor_cp

		The Classpad family of calculators, e.g. the fx-CP400.

	.. c:macro:: casio_filefor_cg

		The Prizm family of calculators, including the fx-CG10, fx-CG20
		and fx-CG50 (Graph 90+E).

	.. c:macro:: casio_filefor_cas

		Ancient calculators supporting the CAS40 and CAS50 protocols.

	.. c:macro:: casio_filefor_casemul

		The CasEmul software.

It is represented by the following object:

.. c:type:: casio_file_t

	A decoded file of one of the supported file formats by libcasio.

Creating and freeing a file
---------------------------

A file can be created using one of the following functions:

.. c:function:: int casio_make_picture(casio_file_t **filep, \
	unsigned int width, unsigned int height)

	Create a picture file using the given dimensions.

.. c:function:: int casio_make_mcs(casio_file_t **filep)

	Create a main memory backup file.

.. c:function:: int casio_make_fkey(casio_file_t **filep, \
	casio_filefor_t filefor, int count)

	Create a function key file for the platform given in ``filefor``,
	with ``count`` slots.

.. c:function:: int casio_make_lang(casio_file_t **filep, \
	casio_filefor_t filefor, int count)

	Create a language file for the platform given in ``filefor``,
	with ``count`` slots.

.. c:function:: int casio_make_addin(casio_file_t **filep, \
	casio_filefor_t filefor, size_t size, char const *name, \
	char const *internal, casio_version_t const *versionp, \
	time_t const *created)

	Create an add-in file for the platform given in ``filefor``,
	with ``size`` bytes for the code, ``name`` as the public name,
	``internal`` as the internal name (usually starting with ``@``),
	``versionp`` pointing to the version structure, and ``created``
	being the time of creation.

Once you're done using a file, you shall use the following function:

.. c:function:: void casio_free_file(casio_file_t *file)

	Free the file and all of its related resources.

Decoding a file
---------------

A file is decoded from a generic stream, using the following function:

.. c:function:: int casio_decode(casio_file_t **filep, \
	char const *filename, tio_stream_t *buffer, \
	casio_filetype_t expected_types)

	Create a file from the stream in ``buffer``, into ``filep``. If you
	have the filename, you shall pass it in ``filename`` (if not, just pass
	``NULL``), this function will also try to guess the file type using the
	detected extension or filename (which has a significance for some
	file formats, e.g. ancient file formats managed by CaS).

	If you don't know what format you expect, pass zero to ``expected_types``.
	Otherwise, use the types as flags, e.g.
	``casio_filetype_picture | casio_filetype_mcs | casio_filetype_storage``
	if you expect to find some pictures (main memory can contain pictures).