Unit alFile

Sets the global I/O encryption password.

Sets the encryption password to be used for all read/write operations on files opened in future using Allegro's packfile functions (whether they are compressed or not), including all the save, load and config routines. Files written with an encryption password cannot be read unless the same password is selected, so be careful: if you forget the key, nobody can make your data come back again! Pass an empty string to return to the normal, non-encrypted mode. If you are using this function to prevent people getting access to your datafiles, be careful not to store an obvious copy of the password in your executable: if there are any strings like "I'm the password for the datafile", it would be fairly easy to get access to your data :-)

Note #1: when writing a packfile, you can change the password to whatever you want after opening the file, without affecting the write operation. On the contrary, when writing a sub-chunk of a packfile, you must make sure that the password that was active at the time the sub-chunk was opened is still active before closing the sub-chunk. This is guaranteed to be true if you didn't call the al_packfile_password routine in the meantime. Read operations, either on packfiles or sub-chunks, have no such restriction.

Note #2: as explained above, the password is used for all read/write operations on files, including for several functions of the library that operate on files without explicitly using packfiles (e.g. al_load_bitmap). The unencrypted mode is mandatory in order for those functions to work. Therefore remember to call al_packfile_password ('') before using them if you previously changed the password. As a rule of thumb, always call al_packfile_password ('') when you are done with operations on packfiles. The only exception to this is custom packfiles created with al_pack_fopen_vtable.

See also

al_pack_fopen

Opens a file according to mode.

al_load_datafile

Loads a datafile into memory in one go.

Opens a file according to mode. The mode may contain any of the flags:

• r - open file for reading.

• w - open file for writing, overwriting any existing data.

• p - open file in packed mode. Data will be compressed as it is written to the file, and automatically uncompressed during read operations. Files created in this mode will produce garbage if they are read without this flag being set.

• ! - open file for writing in normal, unpacked mode, but add the value AL_F_NOPACK_MAGIC to the start of the file, so that it can later be opened in packed mode and Allegro will automatically detect that the data does not need to be decompressed.

Instead of these flags, one of the constants AL_F_READ, AL_F_WRITE, AL_F_READ_PACKED, AL_F_WRITE_PACKED or AL_F_WRITE_NOPACK may be used as the mode parameter.

The packfile functions also understand several "magic" filenames that are used for special purposes. These are in the form filename.dat#object_name and opens a specific object from a datafile, and read from it as if it was a regular file. You can treat nested datafiles exactly like a normal directory structure, for example you could open 'filename.dat#graphics/level1/mapdata'.

With these special filenames, the contents of a datafile object or appended file can be read in an identical way to a normal disk file, so any of the file access functions in Allegro (eg. al_set_config_file) can be used to read from them. Note that you can't write to these special files, though: the fake file is read only. Also, you must save your datafile uncompressed or with per-object compression if you are planning on loading individual objects from it (otherwise there will be an excessive amount of seeking when it is read).

Finally, be aware that the special Allegro object types aren't the same format as the files you import the data from. When you import data like bitmaps or samples into the grabber, they are converted into a special Allegro-specific format, but the `#' marker file syntax reads the objects as raw binary chunks. This means that if, for example, you want to use al_load_bitmap to read an image from a datafile, you should import it as a binary block rather than as an AL_BITMAP object.

Returns

on success, a pointer of type AL_PACKFILEptr, and on error a Nil and stores an error code in al_errno. An attempt to read a normal file in packed mode will cause al_errno to be set to EDOM.

See also

al_pack_fclose

Closes the stream f previously opened with al_pack_fopen.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

al_packfile_password

Sets the global I/O encryption password.

al_pack_fread

Reads n bytes from the stream f, storing them at the memory location pointed to by p.

Creates a new packfile structure that uses the functions specified in the vtable instead of the standard functions. The data pointer by `vtable' and `userdata' must remain available for the lifetime of the created packfile.

While the created packfile structure can be used with other Allegro functions, there are two limitations. First, opening chunks using al_pack_fopen_chunk on top of the returned packfile is not possible at this time. And al_packfile_password does not have any effect on packfiles opened with al_pack_fopen_vtable.

Returns

on success,a pointer to a AL_PACKFILEptr structure, and on error it returns Nil and stores an error code in al_errno.

See also

al_pack_fopen

Opens a file according to mode.

Closes the stream f previously opened with al_pack_fopen. After you have closed the stream, performing operations on it will yield errors in your application (e.g. crash it) or even block your OS.

Returns

zero on success or an error code which is also stored in al_errno. This function can fail only when writing to files: if the file was opened in read mode, it will always succeed.

Moves the position indicator of the stream f. This only supports forward movements relative to the current position and in read-only streams, so don't use negative offsets. Note that seeking is very slow when reading compressed files, and so should be avoided unless you are sure that the file is not compressed.

Returns

True on success, False on failure, storing the error code in al_errno.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

Opens a sub-chunk of a file. Chunks are primarily intended for use by the datafile code, but they may also be useful for your own file routines. A chunk provides a logical view of part of a file, which can be compressed as an individual entity and will automatically insert and check length counts to prevent reading past the end of the chunk. The AL_PACKFILEptr parameter is a previously opened file, and Pack is a boolean parameter which will turn compression on for the sub-chunk if it is True. Example:

VAR
  OutputFile: AL_PACKFILEptr;
BEGIN
  OutputFile := al_pack_fopen ('out.raw', 'w!');
      ...
  OutputFile := al_pack_fopen_chunk (OutputFile, TRUE);
  IF OutputFile = NIL THEN
    abort_on_error ('Error saving data!');
      ...
  OutputFile := al_pack_fclose_chunk (OutputFile);

The data written to the chunk will be prefixed with two length counts (32-bit, a.k.a. big-endian). For uncompressed chunks these will both be set to the size of the data in the chunk. For compressed chunks (created by setting the Pack flag), the first length will be the raw size of the chunk, and the second will be the negative size of the uncompressed data.

To read the chunk, use the following code:

VAR
  InputFile: AL_PACKFILEptr;
BEGIN
  InputFile := al_pack_fopen ('out.raw', 'rp');
      ...
  InputFile := al_pack_fopen_chunk (InputFile, TRUE);
      ...
  InputFile := al_pack_fclose_chunk (InputFile);

This sequence will read the length counts created when the chunk was written, and automatically decompress the contents of the chunk if it was compressed. The length will also be used to prevent reading past the end of the chunk (Allegro will return EOF if you attempt this), and to automatically skip past any unread chunk data when you call al_pack_fclose_chunk.

Chunks can be nested inside each other by making repeated calls to al_pack_fopen_chunk. When writing a file, the compression status is inherited from the parent file, so you only need to set the pack flag if the parent is not compressed but you want to pack the chunk data. If the parent file is already open in packed mode, setting the pack flag will result in data being compressed twice: once as it is written to the chunk, and again as the chunk passes it on to the parent file.

Returns

a pointer to the sub-chunked AL_PACKFILEptr, or Nil if there was some error (eg. you are using a custom AL_PACKFILEptr vtable).

See also

al_pack_fclose_chunk

Closes a sub-chunk of a file, previously obtained by calling al_pack_fopen_chunk.

al_pack_fopen

Opens a file according to mode.

Closes a sub-chunk of a file, previously obtained by calling al_pack_fopen_chunk. Returns a pointer to the parent of the sub-chunk you just closed.

Returns

Nil if there was some error (eg. you tried to close a AL_PACKFILEptr which wasn't sub-chunked).

Returns the next character from the stream `f', or EOF if the end of the file has been reached.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fread

Reads n bytes from the stream f, storing them at the memory location pointed to by p.

al_pack_putc

Puts a character in the stream f.

Puts a character in the stream f.

Returns

the character written on success, or EOF on error.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fwrite

Writes n bytes from the stream f, storing them at the memory location pointed to by p.

al_pack_getc

Returns the next character from the stream `f', or EOF if the end of the file has been reached.

Finds out if you have reached the end of the file. It does not wait for you to attempt to read beyond the end of the file, contrary to the ISO C feof function. The only way to know whether you have read beyond the end of the file is to check the return value of the read operation you use (and be wary of al_pack_*getl as EOF is also a valid return value with these functions).

Returns

True if you are at the end of the file, False otherwise.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

al_pack_ferror

Tells if an error occurred during an operation on the stream.

Tells if an error occurred during an operation on the stream. Since EOF is used to report errors by some functions, it's often better to use the al_pack_feof function to check explicitly for end of file and al_pack_ferror to check for errors. Both functions check indicators that are part of the internal state of the stream to detect correctly the different situations.

Returns

nonzero if the error indicator for the stream is set, meaning that an error has occurred during a previous operation on the stream.

Like al_pack_getc, but reads a 16-bit word from a file, using Intel byte ordering (least significant byte first, a.k.a. little-endian).

Like al_pack_getc, but reads a 32-bit word from a file, using Intel byte ordering (least significant byte first, a.k.a. little-endian).

Like al_pack_putc, but writes a 16-bit word to a file, using Intel byte ordering (least significant byte first, a.k.a. little-endian).

Like al_pack_putc, but writes a 32-bit word to a file, using Intel byte ordering (least significant byte first, a.k.a. little-endian).

Like al_pack_getc, but reads a 16-bit word from a file, using Motorola byte ordering (most significant byte first, a.k.a. big-endian).

Like al_pack_getc, but reads a 32-bit word from a file, using Motorola byte ordering (most significant byte first, a.k.a. big-endian).

Like al_pack_putc, but writes a 16-bit word from a file, using Motorola byte ordering (most significant byte first, a.k.a. big-endian).

Like al_pack_putc, but writes a 32-bit word from a file, using Motorola byte ordering (most significant byte first, a.k.a. big-endian).

Reads n bytes from the stream f, storing them at the memory location pointed to by p.

Returns

the number of bytes read, which will be less than n if EOF is reached or an error occurs. Error codes are stored in al_errno.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

al_pack_feof

Finds out if you have reached the end of the file.

Writes n bytes from the stream f, storing them at the memory location pointed to by p.

Returns

the number of bytes written, which will be less than n if EOF is reached or an error occurs. Error codes are stored in al_errno.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

al_pack_feof

Finds out if you have reached the end of the file.

Puts a character back to the file's input buffer. Like with ungetc from libc, only a single push back is guaranteed.

Note: al_pack_fgets internally uses al_pack_ungetc, so never use al_pack_ungetc directly after using al_pack_fgets on a AL_PACKFILEptr.

Returns

c on success, or EOF on error.

See also

al_pack_getc

Returns the next character from the stream `f', or EOF if the end of the file has been reached.

Reads a line from the stream f and returns it. Stops when a linefeed is encountered, or max bytes have been read. The end of line is handled by detecting the right combination of characters for the platform. This supports CR-LF (DOS/Windows), LF (Unix), and CR (Mac) formats. However, the trailing carriage return is not included in the returned string, in order to provide easy code portability across platforms. If you need the carriage return, use al_pack_fread and/or al_pack_getc instead.

Note: This function internally may make calls to al_pack_ungetc, so you cannot use al_pack_ungetc directly afterwards.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

Writes a string to the stream f. The input string is converted from the current text encoding format to UTF-8 before writing. Newline characters are written as `\r\n' on DOS and Windows platforms. If you don't want this behaviour, use al_pack_fwrite and/or al_pack_putc instead.

Returns

True on success or False on error.

See also

al_pack_fopen

Opens a file according to mode.

al_pack_fopen_chunk

Opens a sub-chunk of a file.

Loads a datafile into memory in one go. If the datafile contains truecolor graphics, you must set the video mode or call al_set_color_conversion before loading it.

Remember to free this datafile to avoid memory leaks.

Returns

a pointer to the AL_DATAFILE, or Nil on error.

See also

al_unload_datafile

Frees all the objects in a datafile.

al_load_datafile_object

Loads a specific object from a datafile.

al_packfile_password

Sets the global I/O encryption password.

Frees all the objects in a datafile. Use this to avoid memory leaks in your program.

See also

al_load_datafile

Loads a datafile into memory in one go.

Loads a specific object from a datafile. This won't work if you strip the object names from the file, and it will be very slow if you save the file with global compression. Example:

VAR
  MusicObject: AL_DATAFILE_OBJECTptr;
  ...
  MusicObject := al_load_datafile_object ('datafile.dat', 'MUSIC');
  al_play_midi (MusicObjectˆ.dat);
  al_unload_datafile_object (MusicObject);
  

Remember to free this DATAFILE later to avoid memory leaks, but use the correct unloading function!

Returns

a pointer to a single AL_DATAFILE_OBJECT element whose dat member points to the object, or Nil if there was an error or there was no object with the requested name.

See also

al_unload_datafile_object

Frees an object previously loaded by al_load_datafile_object.

al_load_datafile

Loads a datafile into memory in one go.

al_set_color_conversion

Specifies how to convert images between the various color depths when reading graphics from external bitmap files or datafiles.

Frees an object previously loaded by al_load_datafile_object. Use this to avoid memory leaks in your program.

Searches an already loaded datafile for an object with the specified name. In the name you can use `/' and `#' separators for nested datafile paths. Example:

VAR
  DataFile: AL_DATAFILEptr;
  Level: AL_DATAFILE_OBJECTptr;
BEGIN
  ...
  Level := al_find_datafile_object (DataFile, Format ('LEVEL_%02d', [LevelNumber]));
  IF Level = NIL THEN
    abort_on_error ('That level doesn't exist!

Returns

a pointer to a AL_DATAFILE_OBJECTptr whose dat member points to the object, or Nil if the object could not be found.

See also

al_load_datafile

Loads a datafile into memory in one go.

al_load_datafile_object

Loads a specific object from a datafile.

A version of al_load_bmp which reads a BMP file from a packfile.

A version of al_load_pcx which reads a PCX file from a packfile.

A version of al_load_tga which reads a TGA file from a packfile.

A version of al_save_bmp which reads a BMP file from a packfile.

A version of al_save_pcx which reads a PCX file from a packfile.

A version of al_save_tga which reads a TGA file from a packfile.

A version of al_load_wav which reads from a packfile.

A version of al_load_voc which reads from a packfile.

To be used to identify an opened file.

Pointer to AL_PACKFILE_VTABLE.

Pointer to AL_DATAFILE_OBJECT.

Pointer to AL_DATAFILE.

Datafile content.

magic number for packed files

magic number for autodetect

magic number for appended data

(AL_ID ('ALL.'))

(AL_ID ('FILE'))

(AL_ID ('DATA'))

(AL_ID ('FONT'))

(AL_ID ('SAMP'))

(AL_ID ('MIDI'))

(AL_ID ('PAT '))

(AL_ID ('FLIC'))

(AL_ID ('BMP '))

(AL_ID ('RLE '))

(AL_ID ('CMP '))

(AL_ID ('XCMP'))

(AL_ID ('PAL '))

(AL_ID ('prop'))

(AL_ID ('NAME'))

End of datafile.