mfile.h

Go to the documentation of this file.

 
#ifndef MFILE_H
#define MFILE_H
 
#if !defined( DEBUG_THRESHOLD )
#  define DEBUG_THRESHOLD 1
#endif /* !DEBUG_THRESHOLD */
 
#ifndef UPRINTF_BUFFER_SZ_MAX
#  define UPRINTF_BUFFER_SZ_MAX 1024
#endif /* !UPRINTF_BUFFER_SZ_MAX */
 
#if !defined( MFILE_MMAP ) && \
   !defined( RETROFLAT_API_WINCE ) && \
   !defined( RETROFLAT_API_PALM )
#  include <sys/stat.h>
#endif /* !MFILE_MMAP */
 
/* TODO: async file_open() call that kicks off download to mem buffer that can
 *       be checked with looped check function.
 */


 
#ifndef MAUG_PATH_SZ_MAX
#  define MAUG_PATH_SZ_MAX 256
#endif /* !MAUG_PATH_SZ_MAX */


#define MFILE_CADDY_TYPE_FILE 0x01

#define MFILE_CADDY_TYPE_MEM_BUFFER 0x80
 /* maug_mfile_types */
 
#define MFILE_FLAG_READ_ONLY     0x01


#define MFILE_READ_FLAG_LSBF     0x01

#define MFILE_READ_FLAG_MSBF     0x01
 
#define MFILE_ASSIGN_FLAG_TRIM_EXT 0x01
 
#ifndef MFILE_TRACE_LVL
#  define MFILE_TRACE_LVL 0
#endif /* !MFILE_TRACE_LVL */
 
#ifndef MFILE_TRACE_CONTENTS_LVL
#  define MFILE_TRACE_CONTENTS_LVL 0
#endif /* !MFILE_TRACE_CONTENTS_LVL */


typedef char retroflat_asset_path[MAUG_PATH_SZ_MAX + 1];

#define mfile_cmp_path( a, b ) strncmp( a, b, MAUG_PATH_SZ_MAX )
 /* maug_retroflt_assets */
 
struct MFILE_CADDY;
typedef struct MFILE_CADDY mfile_t;
 
typedef off_t (*mfile_has_bytes_t)( struct MFILE_CADDY* p_file );
typedef MERROR_RETVAL (*mfile_read_byte_t)(
   struct MFILE_CADDY* p_file, uint8_t* buf );
typedef MERROR_RETVAL (*mfile_read_block_t)(
   struct MFILE_CADDY* p_file, uint8_t* buf, size_t buf_sz );
typedef MERROR_RETVAL (*mfile_seek_t)( struct MFILE_CADDY* p_file, off_t pos );
typedef MERROR_RETVAL (*mfile_read_int_t)(
   struct MFILE_CADDY* p_file, uint8_t* buf, size_t buf_sz, uint8_t flags );
typedef MERROR_RETVAL (*mfile_read_line_t)(
   struct MFILE_CADDY* p_file, char* buf, off_t buf_sz, uint8_t flags );
typedef MERROR_RETVAL (*mfile_printf_t)(
   struct MFILE_CADDY* p_file, uint8_t flags, const char* fmt, ... );
 
off_t mfile_mem_has_bytes( struct MFILE_CADDY* p_file );
MERROR_RETVAL mfile_mem_read_byte( struct MFILE_CADDY* p_file, uint8_t* buf );
MERROR_RETVAL mfile_mem_read_block(
   struct MFILE_CADDY* p_file, uint8_t* buf, size_t buf_sz );
MERROR_RETVAL mfile_mem_seek( struct MFILE_CADDY* p_file, off_t pos );
MERROR_RETVAL mfile_mem_read_line(
   struct MFILE_CADDY* p_f, char* buffer, off_t buffer_sz, uint8_t flags );
MERROR_RETVAL mfile_mem_vprintf(
   mfile_t* p_file, uint8_t flags, const char* fmt, va_list args );

typedef MERROR_RETVAL (*mfile_vprintf_t)(
   struct MFILE_CADDY* p_file, uint8_t flags, const char* fmt, va_list args );
 
/* Load the platform-specific file API. */
#include <mrapifil.h>
#include <mrapilog.h>
 
struct MFILE_CADDY {
   uint8_t type;
   union MFILE_HANDLE h;
   off_t sz;
   off_t last_read;
   off_t mem_cursor;
   uint8_t* mem_buffer;
   uint8_t flags;
   mfile_has_bytes_t has_bytes;
   mfile_read_byte_t read_byte;
   mfile_read_block_t read_block;
   mfile_seek_t seek;
   mfile_read_int_t read_int;
   mfile_read_line_t read_line;
   mfile_printf_t printf;
   mfile_vprintf_t vprintf;
};
 
typedef struct MFILE_CADDY mfile_t;

 
MERROR_RETVAL mfile_assign_path(
   retroflat_asset_path tgt, const retroflat_asset_path src, uint8_t flags );

 
off_t mfile_file_has_bytes( struct MFILE_CADDY* p_file );
 
MERROR_RETVAL mfile_file_read_byte( struct MFILE_CADDY* p_file, uint8_t* buf );
 
MERROR_RETVAL mfile_file_read_block(
   struct MFILE_CADDY* p_file, uint8_t* buf, size_t buf_sz );
 
MERROR_RETVAL mfile_file_read_int(
   struct MFILE_CADDY* p_f, uint8_t* buf, size_t buf_sz, uint8_t flags );
 
MERROR_RETVAL mfile_file_seek( struct MFILE_CADDY* p_file, off_t pos );
 
MERROR_RETVAL mfile_file_read_line(
   struct MFILE_CADDY* p_f, char* buffer, off_t buffer_sz, uint8_t flags );
 
MERROR_RETVAL mfile_file_printf(
   struct MFILE_CADDY* p_f, uint8_t flags, const char* fmt, ... );
 
MERROR_RETVAL mfile_file_vprintf(
   struct MFILE_CADDY* p_f, uint8_t flags, const char* fmt, va_list args );
 
#define mfile_check_lock( p_file ) (NULL != (p_file)->mem_buffer)
 
#define mfile_get_sz( p_file ) ((p_file)->sz)

MERROR_RETVAL mfile_lock_buffer( MAUG_MHANDLE, off_t, mfile_t* p_file );

MERROR_RETVAL mfile_open_read( const char* filename, mfile_t* p_file );
 
MERROR_RETVAL mfile_open_write( const char* filename, mfile_t* p_file );

void mfile_close( mfile_t* p_file );
 
#ifdef MFILE_C
 
#include <mrapifil.h>
#include <mrapilog.h>
 
MERROR_RETVAL mfile_assign_path(
   retroflat_asset_path tgt, const retroflat_asset_path src, uint8_t flags
) {
   MERROR_RETVAL retval = MERROR_OK;
   char* ext_ptr = NULL;
 
   maug_snprintf( tgt, MAUG_PATH_SZ_MAX, "%s", src );
 
   if( MFILE_ASSIGN_FLAG_TRIM_EXT == (MFILE_ASSIGN_FLAG_TRIM_EXT & flags) ) {
      ext_ptr = maug_strrchr( tgt, '.' );
      if( NULL != ext_ptr ) {
         *ext_ptr = '\0';
      }
   }
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_file_read_int(
   struct MFILE_CADDY* p_file, uint8_t* buf, size_t buf_sz, uint8_t flags
) {
   MERROR_RETVAL retval = MERROR_OK;
 
   if(
#ifdef MAUG_LSBF
      MFILE_READ_FLAG_LSBF == (MFILE_READ_FLAG_LSBF & flags)
#elif defined( MAUG_MSBF )
      MFILE_READ_FLAG_MSBF != (MFILE_READ_FLAG_MSBF & flags)
#endif
   ) {
      debug_printf( MFILE_TRACE_LVL, "reading integer forward" );
      /* Shrink the buffer moving right and read into it. */
      retval = p_file->read_block( p_file, buf, buf_sz );
 
   } else {
      debug_printf( MFILE_TRACE_LVL, "reading integer reversed" );
      /* Move to the end of the output buffer and read backwards. */
      while( 0 < buf_sz ) {
         retval = p_file->read_byte( p_file, (buf + (buf_sz - 1)) );
         maug_cleanup_if_not_ok();
         buf_sz--;
      }
   }
 
cleanup:
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_file_printf(
   struct MFILE_CADDY* p_file, uint8_t flags, const char* fmt, ...
) {
   MERROR_RETVAL retval = MERROR_OK;
   va_list vargs;
 
   va_start( vargs, fmt );
   retval = p_file->vprintf( p_file, flags, fmt, vargs );
   va_end( vargs );
 
   return retval;
}
 
/* === */
 
off_t mfile_mem_has_bytes( struct MFILE_CADDY* p_file ) {
   return p_file->sz - p_file->mem_cursor;
}
 
/* === */
 
MERROR_RETVAL mfile_mem_read_byte( struct MFILE_CADDY* p_file, uint8_t* buf ) {
   return p_file->read_block( p_file, buf, 1 );
}
 
/* === */
 
MERROR_RETVAL mfile_mem_read_block(
   struct MFILE_CADDY* p_file, uint8_t* buf, size_t buf_sz
) {
 
   if( p_file->mem_cursor >= p_file->sz ) {
      return MERROR_FILE;
   }
 
   while( 0 < buf_sz-- ) {
      *(buf++) = p_file->mem_buffer[p_file->mem_cursor++];
   }
 
   return MERROR_OK;
}
 
/* === */
 
MERROR_RETVAL mfile_mem_seek( struct MFILE_CADDY* p_file, off_t pos ) {
   MERROR_RETVAL retval = MERROR_OK;
 
   assert( MFILE_CADDY_TYPE_MEM_BUFFER == p_file->type );
 
   p_file->mem_cursor = pos;
 
   debug_printf( MFILE_TRACE_LVL,
      "seeking memory buffer to position " OFF_T_FMT " (" OFF_T_FMT ")",
      pos, p_file->mem_cursor );
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_mem_read_line(
   struct MFILE_CADDY* p_f, char* buffer, off_t buffer_sz, uint8_t flags
) {
   MERROR_RETVAL retval = MERROR_OK;
   off_t i = 0;
 
   assert( MFILE_CADDY_TYPE_MEM_BUFFER == p_f->type );
 
   while( i < buffer_sz - 1 && p_f->has_bytes( p_f ) ) {
      /* Check for potential overflow. */
      if( i + 1 >= buffer_sz ) {
         error_printf( "overflow reading string from file!" );
         retval = MERROR_FILE;
         break;
      }
 
      p_f->read_int( p_f, (uint8_t*)&(buffer[i]), 1, 0 );
      if( '\n' == buffer[i] ) {
         /* Break on newline and overwrite it below. */
         break;
      }
      i++;
   }
 
   assert( i < buffer_sz ); /* while() above stops before buffer_sz! */
 
   /* Append a null terminator. */
   buffer[i] = '\0';
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_mem_vprintf(
   mfile_t* p_file, uint8_t flags, const char* fmt, va_list args
) {
   MERROR_RETVAL retval = MERROR_OK;
 
   if( MFILE_FLAG_READ_ONLY == (MFILE_FLAG_READ_ONLY & p_file->flags) ) {
      return MERROR_FILE;
   }
 
   /* TODO: Enable writing to memory buffer. */
   error_printf( "writing to memory buffer not currently supported!" );
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_lock_buffer(
   MAUG_MHANDLE handle, off_t handle_sz,  mfile_t* p_file
) {
   MERROR_RETVAL retval = MERROR_OK;
 
   debug_printf( 1,
      "locking handle %p as file %p (" OFF_T_FMT " bytes)...",
      handle, p_file, handle_sz );
 
   maug_mzero( p_file, sizeof( struct MFILE_CADDY ) );
   maug_mlock( handle, p_file->mem_buffer );
   p_file->type = MFILE_CADDY_TYPE_MEM_BUFFER;
 
   p_file->has_bytes = mfile_mem_has_bytes;
   p_file->read_byte = mfile_mem_read_byte;
   p_file->read_block = mfile_mem_read_block;
   p_file->read_int = mfile_file_read_int;
   p_file->seek = mfile_mem_seek;
   p_file->read_line = mfile_mem_read_line;
 
   p_file->sz = handle_sz;
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_open_read( const char* filename, mfile_t* p_file ) {
   MERROR_RETVAL retval = MERROR_OK;
 
   /* Call the platform-specific actual file opener from mrapifil.h. */
   retval = mfile_plt_open_read( filename, p_file );
 
   return retval;
}
 
/* === */
 
MERROR_RETVAL mfile_open_write( const char* filename, mfile_t* p_file ) {
   MERROR_RETVAL retval = MERROR_OK;
 
   retval = mfile_plt_open_write( filename, p_file );
 
   return retval;
}
 
/* === */
 
void mfile_close( mfile_t* p_file ) {
#  ifdef MFILE_MMAP
   munmap( bytes_ptr_h, bytes_sz );
#  else
   /* maug_mfree( bytes_ptr_h ); */
   switch( p_file->type ) {
   case 0:
      /* Do nothing silently. */
      break;
 
   case MFILE_CADDY_TYPE_FILE:
      mfile_plt_close( p_file );
      p_file->type = 0;
      break;
 
   case MFILE_CADDY_TYPE_MEM_BUFFER:
      if( NULL != p_file->mem_buffer ) {
         maug_munlock( p_file->h.mem, p_file->mem_buffer );
         debug_printf( 1, "unlocked handle %p from file %p...",
            p_file->h.mem, p_file );
         p_file->type = 0;
      }
      break;
      
   default:
      error_printf( "unknown file type: %d", (p_file)->type );
      break;
   }
#  endif /* MFILE_MMAP */
}
 
#endif /* MFILE_C */
 /* maug_mfile */
 
#endif /* !MFILE_H */