##################
Loading .red Files
##################


You gain some nice benefits when using the .red file format to load your data. RED files can be read both from disk or from memory depending on the stream you pass to the loading method. This is quite useful as it authorizes, for examples, inter-process in-memory data exchange or accessing to .red files from other archive formats. The .red file loader is multi-threaded meaning that you'll get quite good performances at reloading huge data files. Data are loaded using the ``RED::IREDFile`` API and later accessed using the ``RED::IDataManager`` API. Both will be extensively detailed in the upcoming sections.

.. include:: /tasks/ta_ca/ta_ca_file/tk_loading_a_red_file.rst

Every .red file starts with a header (``RED::FileHeader``) which is returned by the ``RED::IREDFile::Load`` method. This header says us more about the version of HOOPS Luminate used to produce the file and the source application. Along with that header, an optional ``RED::FileInfo`` structure may also be provided. This contains information about how to process/render the loaded data in a way similar to how it was processed/rendered in the source application. You should considered this more as hints than strict recommendations (after all, it's optional).

Loaded data are stored into contexts in the RED data manager which can be retrieved from the RED resource manager using ``RED::IResourceManager::GetDataManager``. This manager implements the ``RED::IDataManager`` interface to get access to stored data. A context corresponds to a whole file or to a single animation track in a file. Hence, each animation track contained in the input .red file will be loaded into a separate context (see :doc:`/book/subjects/bk_rff/bk_redfileformat_save` under the section **Recording Animation Tracks** for details about multiple animation tracks). So, when the loading is successful, the context array is returned with at least one new entry. Contexts are logical views of the content of a .red file. They let you access to parts of .red file even after it may have been merged with other .red files into the ``RED::IDataManager``.

************************
Accessing to Loaded Data
************************

With the list of contexts as returned by the RED::IREDFile::Load method and the access to the RED::IDataManager interface, you can retrieve any loaded data.

.. include:: /tasks/ta_ca/ta_ca_file/tk_accessing_to_loaded_data.rst

RED files can be saved encrypted for better security in file exchanges. 

****************************
How to Load Encrypted Files?
****************************

You must first determine if a given file is encrypted or not. To do so, just call the ``RED::IREDFile::Load`` method with no encryption key and check for the returned code. If it's ``RED_OK``, then everything went fine and the data were successfully loaded (and were not encrypted). If ``RED_ENCRYPTED_FILE`` is returned, then the file is encrypted and the user must be asked for the right encryption key. Once he supplied it, ``RED::IREDFile::Load`` can be called again with the key and should return ``RED_OK``. Otherwise, another ``RED_RC`` code is returned describing the issue.

.. include:: /tasks/ta_ca/ta_ca_file/tk_load_encrypted_red_file.rst

If a wrong encryption key is supplied, you'll most of the time end with a ``RED_RC`` error returned by the loading call. As the input key can't be verified, the decrypting process will produce an error at any random time during the loading and must be considered as not meaningful.
 
*********************
Handling Unknown Data
*********************

The .red file format can be extended by the user to integrate custom application data or complementary information. It's also a living standard and new chunks of data can be added to new versions of the file format. Hence, HOOPS Luminate offers a mechanism to handle cases where unknown data are encountered while loading a .red file (file is newer than the loader or custom chunks are found). This is known as the unknown chunk policy and can be set to the ``RED::StreamingPolicy`` by calling ``RED::StreamingPolicy::SetUnknownChunkPolicy``. 

By default, the policy is set to ``RED::StreamingPolicy::UCP_ABORT`` which means that an unknown chunk will make the loading process to return with an error. But the user can choose to perform any other action depending on the chunk actually encountered. In that case, the ``RED::StreamingPolicy::UCP_ASK`` policy can be set and a user callback will be called instead of aborting.

The :doc:`/tutorials/workflows/wf_misc/wf_saving_and_reloading_a_custom_container` tutorial illustrates how to reload a .red file saved with a custom chunk.