src/fileref.c

   1 #include <errno.h>
   2 #include <unistd.h>
   3 #include <string.h>
   4 #include <gtk/gtk.h>
   5 #include <glib/gstdio.h>
   6 #include "fileref.h"
   7 #include "magic.h"
   8 #include "chimara-glk-private.h"
   9
  10 extern ChimaraGlkPrivate *glk_data;
  11
  12 /**
  13  * glk_fileref_iterate:
  14  * @fref: A file reference, or %NULL.
  15  * @rockptr: Return location for the next fileref's rock, or %NULL.
  16  *
  17  * Iterates through all the existing filerefs. See <link
  18  * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
  19  * Objects</link>.
  20  *
  21  * Returns: the next file reference, or %NULL if there are no more.
  22  */
  23 frefid_t
  24 glk_fileref_iterate(frefid_t fref, glui32 *rockptr)
  25 {
  26         VALID_FILEREF_OR_NULL(fref, return NULL);
  27
  28         GList *retnode;
  29
  30         if(fref == NULL)
  31                 retnode = glk_data->fileref_list;
  32         else
  33                 retnode = fref->fileref_list->next;
  34         frefid_t retval = retnode? (frefid_t)retnode->data : NULL;
  35
  36         /* Store the fileref's rock in rockptr */
  37         if(retval && rockptr)
  38                 *rockptr = glk_fileref_get_rock(retval);
  39
  40         return retval;
  41 }
  42
  43 /**
  44  * glk_fileref_get_rock:
  45  * @fref: A file reference.
  46  *
  47  * Retrieves the file reference @fref's rock value. See <link
  48  * linkend="chimara-Rocks">Rocks</link>.
  49  *
  50  * Returns: A rock value.
  51  */
  52 glui32
  53 glk_fileref_get_rock(frefid_t fref)
  54 {
  55         VALID_FILEREF(fref, return 0);
  56         return fref->rock;
  57 }
  58
  59 /* Internal function: create a fileref using the given parameters. */
  60 static frefid_t
  61 fileref_new(gchar *filename, glui32 rock, glui32 usage, glui32 orig_filemode)
  62 {
  63         g_return_val_if_fail(filename != NULL, NULL);
  64
  65         frefid_t f = g_new0(struct glk_fileref_struct, 1);
  66         f->magic = MAGIC_FILEREF;
  67         f->rock = rock;
  68         f->filename = g_strdup(filename);
  69         f->usage = usage;
  70         f->orig_filemode = orig_filemode;
  71
  72         /* Add it to the global fileref list */
  73         glk_data->fileref_list = g_list_prepend(glk_data->fileref_list, f);
  74         f->fileref_list = glk_data->fileref_list;
  75
  76         return f;
  77 }
  78
  79 /**
  80  * glk_fileref_create_temp:
  81  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
  82  * @rock: The new fileref's rock value.
  83  *
  84  * Creates a reference to a temporary file. It is always a new file (one which
  85  * does not yet exist). The file (once created) will be somewhere out of the
  86  * player's way.
  87  *
  88  * <note><para>
  89  *   This is why no name is specified; the player will never need to know it.
  90  * </para></note>
  91  *
  92  * A temporary file should never be used for long-term storage. It may be
  93  * deleted automatically when the program exits, or at some later time, say
  94  * when the machine is turned off or rebooted. You do not have to worry about
  95  * deleting it yourself.
  96  *
  97  * Returns: A new fileref, or #NULL if the fileref creation failed.
  98  */
  99 frefid_t
 100 glk_fileref_create_temp(glui32 usage, glui32 rock)
 101 {
 102         /* Get a temp file */
 103         GError *error = NULL;
 104         gchar *filename = NULL;
 105         gint handle = g_file_open_tmp("glkXXXXXX", &filename, &error);
 106         if(handle == -1)
 107         {
 108                 WARNING_S("Error creating temporary file", error->message);
 109                 if(filename)
 110                         g_free(filename);
 111                 return NULL;
 112         }
 113         if(close(handle) == -1) /* There is no g_close() */
 114         {
 115                 IO_WARNING( "Error closing temporary file", filename, g_strerror(errno) );
 116                 if(filename)
 117                         g_free(filename);
 118                 return NULL;
 119         }
 120
 121         frefid_t f = fileref_new(filename, rock, usage, filemode_Write);
 122         g_free(filename);
 123         return f;
 124 }
 125
 126 /**
 127  * glk_fileref_create_by_prompt:
 128  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
 129  * @fmode: File mode, contolling the dialog's behavior.
 130  * @rock: The new fileref's rock value.
 131  *
 132  * Creates a reference to a file by asking the player to locate it. The library
 133  * may simply prompt the player to type a name, or may use a platform-native
 134  * file navigation tool. (The prompt, if any, is inferred from the usage
 135  * argument.)
 136  *
 137  * <note><title>Chimara</title>
 138  * <para>
 139  * Chimara uses a <link
 140  * linkend="gtk-GtkFileChooserDialog">GtkFileChooserDialog</link>.
 141  * </para></note>
 142  *
 143  * @fmode must be one of these values:
 144  * <variablelist>
 145  * <varlistentry>
 146  *   <term>#filemode_Read</term>
 147  *   <listitem><para>The file must already exist; and the player will be asked
 148  *   to select from existing files which match the usage.</para></listitem>
 149  * </varlistentry>
 150  * <varlistentry>
 151  *   <term>#filemode_Write</term>
 152  *   <listitem><para>The file should not exist; if the player selects an
 153  *   existing file, he will be warned that it will be replaced.
 154  *   </para></listitem>
 155  * </varlistentry>
 156  * <varlistentry>
 157  *   <term>#filemode_ReadWrite</term>
 158  *   <listitem><para>The file may or may not exist; if it already exists, the
 159  *   player will be warned that it will be modified.</para></listitem>
 160  * </varlistentry>
 161  * <varlistentry>
 162  *   <term>#filemode_WriteAppend</term>
 163  *   <listitem><para>Same behavior as #filemode_ReadWrite.</para></listitem>
 164  * </varlistentry>
 165  * </variablelist>
 166  *
 167  * The @fmode argument should generally match the @fmode which will be used to
 168  * open the file.
 169  *
 170  * <note><para>
 171  *   It is possible that the prompt or file tool will have a
 172  *   <quote>cancel</quote> option. If the player chooses this,
 173  *   glk_fileref_create_by_prompt() will return %NULL. This is a major reason
 174  *   why you should make sure the return value is valid before you use it.
 175  * </para></note>
 176  *
 177  * Returns: A new fileref, or #NULL if the fileref creation failed or the
 178  * dialog was canceled.
 179  */
 180 frefid_t
 181 glk_fileref_create_by_prompt(glui32 usage, glui32 fmode, glui32 rock)
 182 {
 183         /* TODO: Remember current working directory and last used filename
 184         for each usage */
 185         GtkWidget *chooser;
 186
 187         gdk_threads_enter();
 188
 189         switch(fmode)
 190         {
 191                 case filemode_Read:
 192                         chooser = gtk_file_chooser_dialog_new("Select a file to open", NULL,
 193                                 GTK_FILE_CHOOSER_ACTION_OPEN,
 194                                 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
 195                                 GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
 196                                 NULL);
 197                         gtk_file_chooser_set_action(GTK_FILE_CHOOSER(chooser),
 198                                 GTK_FILE_CHOOSER_ACTION_OPEN);
 199                         break;
 200                 case filemode_Write:
 201                         chooser = gtk_file_chooser_dialog_new("Select a file to save to", NULL,
 202                                 GTK_FILE_CHOOSER_ACTION_SAVE,
 203                                 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
 204                                 GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
 205                                 NULL);
 206                         gtk_file_chooser_set_action(GTK_FILE_CHOOSER(chooser),
 207                                 GTK_FILE_CHOOSER_ACTION_SAVE);
 208                         gtk_file_chooser_set_do_overwrite_confirmation(
 209                                 GTK_FILE_CHOOSER(chooser), TRUE);
 210                         break;
 211                 case filemode_ReadWrite:
 212                 case filemode_WriteAppend:
 213                         chooser = gtk_file_chooser_dialog_new("Select a file to save to", NULL,
 214                                 GTK_FILE_CHOOSER_ACTION_SAVE,
 215                                 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
 216                                 GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
 217                                 NULL);
 218                         gtk_file_chooser_set_action(GTK_FILE_CHOOSER(chooser),
 219                                 GTK_FILE_CHOOSER_ACTION_SAVE);
 220                         break;
 221                 default:
 222                         ILLEGAL_PARAM("Unknown file mode: %u", fmode);
 223                         gdk_threads_leave();
 224                         return NULL;
 225         }
 226
 227         if(gtk_dialog_run( GTK_DIALOG(chooser) ) != GTK_RESPONSE_ACCEPT)
 228         {
 229                 gtk_widget_destroy(chooser);
 230                 gdk_threads_leave();
 231                 return NULL;
 232         }
 233         gchar *filename =
 234                 gtk_file_chooser_get_filename( GTK_FILE_CHOOSER(chooser) );
 235         frefid_t f = fileref_new(filename, rock, usage, fmode);
 236         g_free(filename);
 237         gtk_widget_destroy(chooser);
 238
 239         gdk_threads_leave();
 240         return f;
 241 }
 242
 243 /**
 244  * glk_fileref_create_by_name:
 245  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
 246  * @name: A filename.
 247  * @rock: The new fileref's rock value.
 248  *
 249  * This creates a reference to a file with a specific name. The file will be
 250  * in a fixed location relevant to your program, and visible to the player.
 251  *
 252  * <note><para>
 253  *   This usually means <quote>in the same directory as your program.</quote>
 254  * </para></note>
 255  * <note><title>Chimara</title>
 256  * <para>
 257  * In Chimara, the file is created in the current working directory.
 258  * </para></note>
 259  *
 260  * Since filenames are highly platform-specific, you should use
 261  * glk_fileref_create_by_name() with care. It is legal to pass any string in the
 262  * name argument. However, the library may have to mangle, transform, or
 263  * truncate the string to make it a legal native filename.
 264  *
 265  * <note><para>
 266  *   For example, if you create two filerefs with the names <quote>File</quote>
 267  *   and <quote>FILE</quote>, they may wind up pointing to the same file; the
 268  *   platform may not support case distinctions in file names. Another example:
 269  *   on a platform where file type is specified by filename suffix, the library
 270  *   will add an appropriate suffix based on the usage; any suffix in the string
 271  *   will be overwritten or added to. For that matter, remember that the period
 272  *   is not a legal character in Acorn filenames...
 273  * </para></note>
 274  *
 275  * The most conservative approach is to pass a string of no more than 8
 276  * characters, consisting entirely of upper-case letters and numbers, starting
 277  * with a letter. You can then be reasonably sure that the resulting filename
 278  * will display all the characters you specify &mdash; in some form.
 279  *
 280  * Returns: A new fileref, or %NULL if the fileref creation failed.
 281  */
 282 frefid_t
 283 glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock)
 284 {
 285         g_return_val_if_fail(name != NULL && strlen(name) > 0, NULL);
 286
 287         /* Find out what encoding filenames are in */
 288         const gchar **charsets; /* Do not free */
 289         g_get_filename_charsets(&charsets);
 290
 291         /* Convert name to that encoding */
 292         GError *error = NULL;
 293         gchar *osname = g_convert(name, -1, charsets[0], "ISO-8859-1", NULL, NULL,
 294                 &error);
 295         if(osname == NULL)
 296         {
 297                 WARNING_S("Error during latin1->filename conversion", error->message);
 298                 return NULL;
 299         }
 300
 301         /* Do any string-munging here to remove illegal characters from filename.
 302         On ext3, the only illegal characters are '/' and '\0'. TODO: Should this
 303         function be allowed to reference files in other directories, or should we
 304         disallow '/'? */
 305
 306         frefid_t f = fileref_new(osname, rock, usage, filemode_ReadWrite);
 307         g_free(osname);
 308         return f;
 309 }
 310
 311 /**
 312  * glk_fileref_create_from_fileref:
 313  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
 314  * @fref: Fileref to copy.
 315  * @rock: The new fileref's rock value.
 316  *
 317  * This copies an existing file reference @fref, but changes the usage. (The
 318  * original fileref is not modified.)
 319  *
 320  * The use of this function can be tricky. If you change the type of the fileref
 321  * (#fileusage_Data, #fileusage_SavedGame, etc), the new reference may or may
 322  * not point to the same actual disk file.
 323  *
 324  * <note><para>
 325  *   This generally depends on whether the platform uses suffixes to indicate
 326  *   file type.
 327  * </para></note>
 328  *
 329  * If you do this, and open both file references for writing, the results are
 330  * unpredictable. It is safest to change the type of a fileref only if it refers
 331  * to a nonexistent file.
 332  *
 333  * If you change the mode of a fileref (#fileusage_TextMode,
 334  * #fileusage_BinaryMode), but leave the rest of the type unchanged, the new
 335  * fileref will definitely point to the same disk file as the old one.
 336  *
 337  * Obviously, if you write to a file in text mode and then read from it in
 338  * binary mode, the results are platform-dependent.
 339  *
 340  * Returns: A new fileref, or %NULL if the fileref creation failed.
 341  */
 342 frefid_t
 343 glk_fileref_create_from_fileref(glui32 usage, frefid_t fref, glui32 rock)
 344 {
 345         VALID_FILEREF(fref, return NULL);
 346         return fileref_new(fref->filename, rock, usage, fref->orig_filemode);
 347 }
 348
 349 /**
 350  * glk_fileref_destroy:
 351  * @fref: Fileref to destroy.
 352  *
 353  * Destroys a fileref which you have created. This does <emphasis>not</emphasis>
 354  * affect the disk file; it just reclaims the resources allocated by the
 355  * <code>glk_fileref_create...</code> function.
 356  *
 357  * It is legal to destroy a fileref after opening a file with it (while the
 358  * file is still open.) The fileref is only used for the opening operation,
 359  * not for accessing the file stream.
 360  */
 361 void
 362 glk_fileref_destroy(frefid_t fref)
 363 {
 364         VALID_FILEREF(fref, return);
 365
 366         glk_data->fileref_list = g_list_delete_link(glk_data->fileref_list, fref->fileref_list);
 367         if(fref->filename)
 368                 g_free(fref->filename);
 369
 370         fref->magic = MAGIC_FREE;
 371         g_free(fref);
 372 }
 373
 374 /**
 375  * glk_fileref_delete_file:
 376  * @fref: A refrence to the file to delete.
 377  *
 378  * Deletes the file referred to by @fref. It does not destroy @fref itself.
 379  */
 380 void
 381 glk_fileref_delete_file(frefid_t fref)
 382 {
 383         VALID_FILEREF(fref, return);
 384         if( glk_fileref_does_file_exist(fref) )
 385                 if(g_unlink(fref->filename) == -1)
 386                         IO_WARNING( "Error deleting file", fref->filename, g_strerror(errno) );
 387 }
 388
 389 /**
 390  * glk_fileref_does_file_exist:
 391  * @fref: A fileref to check.
 392  *
 393  * Checks whether the file referred to by @fref exists.
 394  *
 395  * Returns: %TRUE (1) if @fref refers to an existing file, and %FALSE (0) if
 396  * not.
 397  */
 398 glui32
 399 glk_fileref_does_file_exist(frefid_t fref)
 400 {
 401         VALID_FILEREF(fref, return 0);
 402         if( g_file_test(fref->filename, G_FILE_TEST_EXISTS) )
 403                 return 1;
 404         return 0;
 405 }
 406