Archive Struct Reference


Public Methods

void Archive_ctor (struct Archive *ptr_archive, char *sz_archive_name)
void Archive_dtor (struct Archive *ptr_archive, int memory_flag)
bool Archive_is_good (struct Archive *ptr_archive)
struct Input* Archive_open (struct Archive *ptr_archive, int entry)
struct Input* Archive_open_Ex (struct Archive *ptr_archive, char *sz_name)
struct Output* Archive_open_write (struct Archive *ptr_archive, int entry)
struct Output* Archive_open_write_Ex (struct Archive *ptr_archive, char *sz_name)
int Archive_count_entries (struct Archive *ptr_archive)
char* Archive_get_name (struct Archive *ptr_archive, int entry)
char* Archive_archive_name (struct Archive *ptr_archive)

Detailed Description

An archive is a file that holds more files inside it, with possible compression of every one of them. Right now only one compression method is supported, but space for 254 more is reserved. You get standard Input* when opening a file from inside the archive, and you should handle it like regular input. If files are not compressed, random access methods can be used for their Input objects.

Currently, compressed streams do not support random access. Using archives is the preferred way to handle large groups of files. Getting files from an archive might be faster than opening a file, especially if there are a lot of them.

You must call the Archive_ctor() function before retrieving a file from an archive and Archive_dtor() afterward. The pointer to the archive of the current application can be obtained in the following manner: 

      #include <cybiko.h>
      ...
      struct module_t main_module;
      ...
      init_module( &main_module );
      //  main_module.m_process->module->archive is the pointer to the
      //  Archive of the current application.
      ...
See also:
File I/O

Member Function Documentation

char * Archive_archive_name ( struct Archive * ptr_archive )
 

Returns the archive name.

Parameters:
ptr_archive   A pointer to an initialized Archive object
Returns:
Name of the archive 
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }

int Archive_count_entries ( struct Archive * ptr_archive )
 

Returns the number of entries (resources) in the archive.

Parameters:
ptr_archive   A pointer to an initialized Archive object
Returns:
The number of entries (resources) in the archive 
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }

void Archive_ctor ( struct Archive * ptr_archive,
char * sz_archive_name )
 

Initializes an Archive object for a specified archive file.

Parameters:
ptr_archive   A pointer to an initialized Archive object
sz_archive_name   The name of the archive file
Returns:
None 
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        } 
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_dtor

void Archive_dtor ( struct Archive * ptr_archive,
int memory_flag )
 

Destructor of an Archive object.
It frees all used resources.

Parameters:
ptr_archive   A pointer to the Archive object to be destroyed
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If malloc() was used to allocate the object's memory, use FREE_MEMORY. If the object was static or allocated in stack, use LEAVE_MEMORY.
Returns:
None 
      #include <cybiko.h>       
      ...
      {     
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_ctor, FREE_MEMORY, LEAVE_MEMORY.

char * Archive_get_name ( struct Archive * ptr_archive,
int entry )
 

Retrieves the name of the Nth entry.

Parameters:
ptr_archive   A pointer to the initialized Archive object.
entry   The element's index in the Archive
Returns:
Name of the entry with the specified index 
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }

bool Archive_is_good ( struct Archive * ptr_archive )
 

Checks whether the Archive object is valid.

Parameters:
ptr_archive   A pointer to the Archive object to be checked
Returns:
TRUE if the Archive object is valid 
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
     }

struct Input * Archive_open ( struct Archive * ptr_archive,
int entry )
 

Opens an Input for the specified resource index.
All files in the archive are numbered. These numbers are often referenced as resource IDs. Archive_open constructs the right kind of stream for an entry and returns it. Use it the same way as a regular stream. Important: don't forget to delete it when you're done with it

Parameters:
ptr_archive   A pointer to an initialized Archive object
entry   The entry number (resource id)
Returns:
Input object to read the specified file from the archive, or NULL if there is no such Id or not enough memory for the operation 
      #include <cybiko.h>
      ...
      {
        struct BitmapSequence movie_frames;
        struct Archive resources;
        struct Input* ptr_input;
        ...
        Archive_ctor( &resources, "movie.dat" );
        if( Archive_is_good( &resources ) )
        {
          ptr_input = Archive_open( &resources, 0 );
          BitmapSequence_ctor( &movie_frames );
          BitmapSequence_load( &movie_frames, ptr_input );
          ...
        }
        ...
        BitmapSequence_dtor( &movie_frames, LEAVE_MEMORY );
        Input_dtor( ptr_input, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open_Ex.

struct Input * Archive_open_Ex ( struct Archive * ptr_archive,
char * sz_name )
 

Opens an Input from the archive for the file named.
It works just like Archive_open() but looks for files by name.

Parameters:
ptr_archive   A pointer to an initialized Archive object
sz_name   The name of the file inside the archive
Returns:
A pointer to a corresponding Input object, or NULL if the file is not found or there is not enough memory to open it. 
      #include <cybiko.h>
      ...
      {
        struct BitmapSequence movie_frames;
        struct Archive resources;
        struct Input* ptr_input;
        ...
        Archive_ctor( &resources, "movie.dat" );
        if( Archive_is_good( &resources ) )
        {
          ptr_input = Archive_open_Ex( &resources, "frames.pic" );
          BitmapSequence_ctor( &movie_frames );
          BitmapSequence_load( &movie_frames, ptr_input );
          ...
        }
        ...
        BitmapSequence_dtor( &movie_frames, LEAVE_MEMORY );
        Input_dtor( ptr_input, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open.

struct Output * Archive_open_write ( struct Archive * ptr_archive,
int entry )
 

All files in the archive are numbered.
These numbers are often referenced as resource IDs. Archive_open_write constructs the right kind of stream for an entry, and returns it. Use it the same way as a regular stream. Important: don't forget to delete it when you're done with it! FILE MUST NOT BE COMPRESSED!

Parameters:
ptr_archive   A pointer to an initialized Archive object.
entry   The entry number (resource ID).
Returns:
Output object to write to the specified archive file; or NULL if there is no such ID, not enough memory for the operation, or the file is compressed 
      #include <cybiko.h>
      ...
      {
        struct Archive resources;
        struct Output* ptr_output;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        { 
          ptr_output = Archive_open_write( &resources, 0);
          Output_write( ptr_output, 
                        game_information, 
                        sizeof( struct GameInformation ) );
          ...
        }
        ...
        Output_dtor( ptr_output, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open_write_Ex.

struct Output * Archive_open_write_Ex ( struct Archive * ptr_archive,
char * sz_name )
 

Opens an Output for the archive file named.
It works just like Archive_open_write, but looks for files by name. Archive_open_write_Ex constructs the right kind of stream for an entry, and returns it. Use it the same way as a regular stream. Important: don't forget to delete it when you're done with it! FILE MUST NOT BE COMPRESSED!

Parameters:
ptr_archive   A pointer to an initialized Archive object.
sz_name   The name of the file inside the archive
Returns:
A pointer to a corresponding Output object; or NULL if the file is not found, there is not enough memory to open it, or the file is compressed. 
      #include <cybiko.h>
      ...
      {
        struct Archive resources;
        struct Output* ptr_output;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          ptr_output = Archive_open_write_Ex( &resources, "game_1" );
          Output_write( ptr_output, 
                        game_information, 
                        sizeof( struct GameInformation ) );
          ...
        }
        ...
        Output_dtor( ptr_output, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open_write.