No need to include empty default signal handlers
[projects/chimara/chimara.git] / libchimara / fileref.c
1 #include <config.h>
2 #include <errno.h>
3 #include <unistd.h>
4 #include <string.h>
5 #include <gtk/gtk.h>
6 #include <glib/gstdio.h>
7 #include <glib/gi18n-lib.h>
8 #include "fileref.h"
9 #include "magic.h"
10 #include "chimara-glk-private.h"
11 #include "gi_dispa.h"
12
13 extern GPrivate glk_data_key;
14
15 /* Internal function: create a fileref using the given parameters. If @basename
16 is NULL, compute a basename from @filename. */
17 frefid_t
18 fileref_new(char *filename, char *basename, glui32 rock, glui32 usage, glui32 orig_filemode)
19 {
20         g_return_val_if_fail(filename != NULL, NULL);
21
22         ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
23
24         frefid_t f = g_new0(struct glk_fileref_struct, 1);
25         f->magic = MAGIC_FILEREF;
26         f->rock = rock;
27         if(glk_data->register_obj)
28                 f->disprock = (*glk_data->register_obj)(f, gidisp_Class_Fileref);
29         
30         f->filename = g_strdup(filename);
31         if(basename)
32                 f->basename = g_strdup(basename);
33         else
34                 f->basename = g_path_get_basename(filename);
35         f->usage = usage;
36         f->orig_filemode = orig_filemode;
37         
38         /* Add it to the global fileref list */
39         glk_data->fileref_list = g_list_prepend(glk_data->fileref_list, f);
40         f->fileref_list = glk_data->fileref_list;
41         
42         return f;
43 }
44
45 static void
46 fileref_close_common(frefid_t fref)
47 {
48         ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
49
50         glk_data->fileref_list = g_list_delete_link(glk_data->fileref_list, fref->fileref_list);
51
52         if(glk_data->unregister_obj)
53         {
54                 (*glk_data->unregister_obj)(fref, gidisp_Class_Fileref, fref->disprock);
55                 fref->disprock.ptr = NULL;
56         }
57         
58         g_free(fref->filename);
59         g_free(fref->basename);
60         
61         fref->magic = MAGIC_FREE;
62         g_free(fref);
63 }
64
65 /**
66  * glk_fileref_iterate:
67  * @fref: A file reference, or %NULL.
68  * @rockptr: Return location for the next fileref's rock, or %NULL.
69  *
70  * Iterates through all the existing filerefs. See <link
71  * linkend="chimara-Iterating-Through-Opaque-Objects">Iterating Through Opaque
72  * Objects</link>.
73  *
74  * Returns: the next file reference, or %NULL if there are no more.
75  */
76 frefid_t
77 glk_fileref_iterate(frefid_t fref, glui32 *rockptr)
78 {
79         VALID_FILEREF_OR_NULL(fref, return NULL);
80
81         ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
82         GList *retnode;
83         
84         if(fref == NULL)
85                 retnode = glk_data->fileref_list;
86         else
87                 retnode = fref->fileref_list->next;
88         frefid_t retval = retnode? (frefid_t)retnode->data : NULL;
89                 
90         /* Store the fileref's rock in rockptr */
91         if(retval && rockptr)
92                 *rockptr = glk_fileref_get_rock(retval);
93                 
94         return retval;
95 }
96
97 /**
98  * glk_fileref_get_rock:
99  * @fref: A file reference.
100  * 
101  * Retrieves the file reference @fref's rock value. See <link 
102  * linkend="chimara-Rocks">Rocks</link>.
103  *
104  * Returns: A rock value.
105  */
106 glui32
107 glk_fileref_get_rock(frefid_t fref)
108 {
109         VALID_FILEREF(fref, return 0);
110         return fref->rock;
111 }
112
113 /**
114  * glk_fileref_create_temp:
115  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
116  * @rock: The new fileref's rock value.
117  *
118  * Creates a reference to a temporary file. It is always a new file (one which
119  * does not yet exist). The file (once created) will be somewhere out of the
120  * player's way.
121  *
122  * <note><para>
123  *   This is why no name is specified; the player will never need to know it.
124  * </para></note>
125  *
126  * A temporary file should never be used for long-term storage. It may be
127  * deleted automatically when the program exits, or at some later time, say
128  * when the machine is turned off or rebooted. You do not have to worry about
129  * deleting it yourself.
130  *
131  * Returns: A new fileref, or #NULL if the fileref creation failed.
132  */ 
133 frefid_t
134 glk_fileref_create_temp(glui32 usage, glui32 rock)
135 {
136         /* Get a temp file */
137         GError *error = NULL;
138         gchar *filename = NULL;
139         gint handle = g_file_open_tmp("glkXXXXXX", &filename, &error);
140         if(handle == -1)
141         {
142                 WARNING_S("Error creating temporary file", error->message);
143                 if(filename)
144                         g_free(filename);
145                 return NULL;
146         }
147         if(close(handle) == -1) /* There is no g_close() */
148         {
149                 IO_WARNING( "Error closing temporary file", filename, g_strerror(errno) );
150                 if(filename)
151                         g_free(filename);
152                 return NULL;
153         }
154         
155         /* Pass a basename of "" to ensure that this file can't be repurposed */
156         frefid_t f = fileref_new(filename, "", rock, usage, filemode_Write);
157         g_free(filename);
158         return f;
159 }
160
161 /**
162  * glk_fileref_create_by_prompt:
163  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
164  * @fmode: File mode, contolling the dialog's behavior.
165  * @rock: The new fileref's rock value.
166  *
167  * Creates a reference to a file by asking the player to locate it. The library
168  * may simply prompt the player to type a name, or may use a platform-native
169  * file navigation tool. (The prompt, if any, is inferred from the usage
170  * argument.)
171  *
172  * <note><title>Chimara</title>
173  * <para>
174  * Chimara uses a <link 
175  * linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>. The default
176  * starting location for the dialog may be set with glkunix_set_base_file().
177  * </para></note>
178  *
179  * @fmode must be one of these values:
180  * <variablelist>
181  * <varlistentry>
182  *   <term>%filemode_Read</term>
183  *   <listitem><para>The file must already exist; and the player will be asked
184  *   to select from existing files which match the usage.</para></listitem>
185  * </varlistentry>
186  * <varlistentry>
187  *   <term>%filemode_Write</term>
188  *   <listitem><para>The file should not exist; if the player selects an
189  *   existing file, he will be warned that it will be replaced.
190  *   </para></listitem>
191  * </varlistentry>
192  * <varlistentry>
193  *   <term>%filemode_ReadWrite</term>
194  *   <listitem><para>The file may or may not exist; if it already exists, the
195  *   player will be warned that it will be modified.</para></listitem>
196  * </varlistentry>
197  * <varlistentry>
198  *   <term>%filemode_WriteAppend</term>
199  *   <listitem><para>Same behavior as %filemode_ReadWrite.</para></listitem>
200  * </varlistentry>
201  * </variablelist>
202  *
203  * The @fmode argument should generally match the @fmode which will be used to
204  * open the file.
205  *
206  * <note><para>
207  *   It is likely that the prompt or file tool will have a <quote>cancel</quote>
208  *   option. If the player chooses this, glk_fileref_create_by_prompt() will
209  *   return %NULL. This is a major reason why you should make sure the return
210  *   value is valid before you use it.
211  * </para></note>
212  *
213  * The recommended file suffixes for files are <filename>.glkdata</filename> for
214  * %fileusage_Data, <filename>.glksave</filename> for %fileusage_SavedGame,
215  * <filename>.txt</filename> for %fileusage_Transcript and
216  * %fileusage_InputRecord.
217  *
218  * Returns: A new fileref, or #NULL if the fileref creation failed or the
219  * dialog was canceled.
220  */
221 frefid_t
222 glk_fileref_create_by_prompt(glui32 usage, glui32 fmode, glui32 rock)
223 {
224         /* TODO: Remember current working directory and last used filename
225         for each usage */
226         GtkWidget *chooser;
227
228         ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
229
230         gdk_threads_enter();
231
232         switch(fmode)
233         {
234                 case filemode_Read:
235                         chooser = gtk_file_chooser_dialog_new("Select a file to open", NULL,
236                                 GTK_FILE_CHOOSER_ACTION_OPEN,
237                                 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
238                                 GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
239                                 NULL);
240                         gtk_file_chooser_set_action(GTK_FILE_CHOOSER(chooser), GTK_FILE_CHOOSER_ACTION_OPEN);
241                         break;
242                 case filemode_Write:
243                         chooser = gtk_file_chooser_dialog_new("Select a file to save to", NULL,
244                                 GTK_FILE_CHOOSER_ACTION_SAVE,
245                                 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
246                                 GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
247                                 NULL);
248                         gtk_file_chooser_set_action(GTK_FILE_CHOOSER(chooser), GTK_FILE_CHOOSER_ACTION_SAVE);
249                         gtk_file_chooser_set_do_overwrite_confirmation(GTK_FILE_CHOOSER(chooser), TRUE);
250                         break;
251                 case filemode_ReadWrite:
252                 case filemode_WriteAppend:
253                         chooser = gtk_file_chooser_dialog_new("Select a file to save to", NULL,
254                                 GTK_FILE_CHOOSER_ACTION_SAVE,
255                                 GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
256                                 GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
257                                 NULL);
258                         gtk_file_chooser_set_action(GTK_FILE_CHOOSER(chooser), GTK_FILE_CHOOSER_ACTION_SAVE);
259                         break;
260                 default:
261                         ILLEGAL_PARAM("Unknown file mode: %u", fmode);
262                         gdk_threads_leave();
263                         return NULL;
264         }
265         
266         /* Set up a file filter with suggested extensions */
267         GtkFileFilter *filter = gtk_file_filter_new();
268         switch(usage & fileusage_TypeMask)
269         {
270                 case fileusage_Data:
271                         gtk_file_filter_set_name(filter, _("Data files (*.glkdata)"));
272                         gtk_file_filter_add_pattern(filter, "*.glkdata");
273                         break;
274                 case fileusage_SavedGame:
275                         gtk_file_filter_set_name(filter, _("Saved games (*.glksave)"));
276                         gtk_file_filter_add_pattern(filter, "*.glksave");
277                         break;
278                 case fileusage_InputRecord:
279                         gtk_file_filter_set_name(filter, _("Text files (*.txt)"));
280                         gtk_file_filter_add_pattern(filter, "*.txt");
281                         break;
282                 case fileusage_Transcript:
283                         gtk_file_filter_set_name(filter, _("Transcript files (*.txt)"));
284                         gtk_file_filter_add_pattern(filter, "*.txt");
285                         break;
286                 default:
287                         ILLEGAL_PARAM("Unknown file usage: %u", usage);
288                         gdk_threads_leave();
289                         return NULL;
290         }
291         gtk_file_chooser_add_filter(GTK_FILE_CHOOSER(chooser), filter);
292
293         /* Add a "text mode" filter for text files */
294         if((usage & fileusage_TypeMask) == fileusage_InputRecord || (usage & fileusage_TypeMask) == fileusage_Transcript)
295         {
296                 filter = gtk_file_filter_new();
297                 gtk_file_filter_set_name(filter, _("All text files"));
298                 gtk_file_filter_add_mime_type(filter, "text/plain");
299                 gtk_file_chooser_add_filter(GTK_FILE_CHOOSER(chooser), filter);
300         }
301
302         /* Add another non-restricted filter */
303         filter = gtk_file_filter_new();
304         gtk_file_filter_set_name(filter, _("All files"));
305         gtk_file_filter_add_pattern(filter, "*");
306         gtk_file_chooser_add_filter(GTK_FILE_CHOOSER(chooser), filter);
307
308         if(glk_data->current_dir)
309                 gtk_file_chooser_set_current_folder(GTK_FILE_CHOOSER(chooser), glk_data->current_dir);
310         
311         if(gtk_dialog_run( GTK_DIALOG(chooser) ) != GTK_RESPONSE_ACCEPT)
312         {
313                 gtk_widget_destroy(chooser);
314                 gdk_threads_leave();
315                 return NULL;
316         }
317         gchar *filename = gtk_file_chooser_get_filename( GTK_FILE_CHOOSER(chooser) );
318         frefid_t f = fileref_new(filename, NULL, rock, usage, fmode);
319         g_free(filename);
320         gtk_widget_destroy(chooser);
321
322         gdk_threads_leave();
323         return f;
324 }
325
326 /**
327  * glk_fileref_create_by_name:
328  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
329  * @name: A filename.
330  * @rock: The new fileref's rock value.
331  *
332  * This creates a reference to a file with a specific name. The file will be
333  * in a fixed location relevant to your program, and visible to the player.
334  *
335  * <note><para>
336  *   This usually means <quote>in the same directory as your program.</quote>
337  * </para></note>
338  * <note><title>Chimara</title>
339  * <para>
340  * In Chimara, the file is created in the directory last set by 
341  * glkunix_set_base_file(), and otherwise in the current working directory.
342  * </para></note>
343  *
344  * Earlier versions of the Glk spec specified that the library may have to
345  * extend, truncate, or change your name argument in order to produce a legal
346  * native filename. This remains true. However, since Glk was originally
347  * proposed, the world has largely reached consensus about what a filename looks
348  * like. Therefore, it is worth including some recommended library behavior
349  * here. Libraries that share this behavior will more easily be able to exchange
350  * files, which may be valuable both to authors (distributing data files for
351  * games) and for players (moving data between different computers or different
352  * applications).
353  *
354  * The library should take the given filename argument, and delete any
355  * characters illegal for a filename. This will include all of the following
356  * characters (and more, if the OS requires it): slash, backslash, angle
357  * brackets (less-than and greater-than), colon, double-quote, pipe (vertical
358  * bar), question-mark, asterisk. The library should also truncate the argument
359  * at the first period (delete the first period and any following characters).
360  * If the result is the empty string, change it to the string
361  * <code>"null"</code>.
362  *
363  * It should then append an appropriate suffix, depending on the usage:
364  * <filename>.glkdata</filename> for %fileusage_Data,
365  * <filename>.glksave</filename> for %fileusage_SavedGame,
366  * <filename>.txt</filename> for %fileusage_Transcript and
367  * %fileusage_InputRecord.
368  *
369  * The above behavior is not a requirement of the Glk spec. Older
370  * implementations can continue doing what they do. Some programs (e.g.
371  * web-based interpreters) may not have access to a traditional filesystem at
372  * all, and to them these recommendations will be meaningless.
373  *
374  * On the other side of the coin, the game file should not press these
375  * limitations. Best practice is for the game to pass a filename containing only
376  * letters and digits, beginning with a letter, and not mixing upper and lower
377  * case. Avoid overly-long filenames.
378  *
379  * <note><para>
380  *   The earlier Glk spec gave more stringent recommendations: <quote>No more
381  *   than 8 characters, consisting entirely of upper-case letters and numbers,
382  *   starting with a letter</quote>. The DOS era is safely contained, if not
383  *   over, so this has been relaxed. The I7 manual recommends <quote>23
384  *   characters or fewer</quote>.
385  * </para></note>
386  *
387  * <note><para>
388  *   To address other complications:</para>
389  *   <itemizedlist>
390  *     <listitem><para>
391  *       Some filesystems are case-insensitive. If you create two filerefs with
392  *       the names <filename>File</filename> and <filename>FILE</filename>, they
393  *       may wind up pointing to the same file, or they may not. Avoid doing
394  *       this.
395  *     </para></listitem>
396  *     <listitem><para>
397  *       Some programs will look for all files in the same directory as the
398  *       program itself (or, for interpreted games, in the same directory as the
399  *       game file). Others may keep files in a data-specific directory
400  *       appropriate for the user (e.g., <filename
401  *       class="directory">~/Library</filename> on MacOS).
402  *     </para></listitem>
403  *     <listitem><para>
404  *       If a game interpreter uses a data-specific directory, there is a
405  *       question of whether to use a common location, or divide it into
406  *       game-specific subdirectories. (Or to put it another way: should the
407  *       namespace of named files be per-game or app-wide?) Since data files may
408  *       be exchanged between games, they should be given an app-wide namespace.
409  *       In contrast, saved games should be per-game, as they can never be
410  *       exchanged. Transcripts and input records can go either way.
411  *     </para></listitem>
412  *     <listitem><para>
413  *       When updating an older library to follow these recommendations,
414  *       consider backwards compatibility for games already installed. When
415  *       opening an existing file (that is, not in a write-only mode) it may be
416  *       worth looking under the older name (suffix) if the newer one does not
417  *       already exist.
418  *     </para></listitem>
419  *     <listitem><para>
420  *       Game-save files are already stored with a variety of file suffixes,
421  *       since that usage goes back to the oldest IF interpreters, long
422  *       predating Glk. It is reasonable to treat them in some special way,
423  *       while hewing closer to these recommendations for data files.
424  *     </para></listitem>
425  *   </itemizedlist>
426  * </note>
427  *
428  * Returns: A new fileref, or %NULL if the fileref creation failed. 
429  */
430 frefid_t
431 glk_fileref_create_by_name(glui32 usage, char *name, glui32 rock)
432 {
433         g_return_val_if_fail(name != NULL && strlen(name) > 0, NULL);
434
435         ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
436
437         /* Do any string-munging here to remove illegal Latin-1 characters from 
438         filename. On ext3, the only illegal characters are '/' and '\0', but the Glk
439         spec calls for removing any other tricky characters. */
440         char *buf = g_malloc(strlen(name));
441         char *ptr, *filename, *extension;
442         int len;
443         for(ptr = name, len = 0; *ptr && *ptr != '.'; ptr++)
444         {
445                 switch(*ptr)
446                 {
447                         case '"': case '\\': case '/': case '>': case '<':
448                         case ':': case '|':     case '?': case '*':
449                                 break;
450                         default:
451                                 buf[len++] = *ptr;
452                 }
453         }
454         buf[len] = '\0';
455
456         /* If there is nothing left, make the name "null" */
457         if(len == 0) {
458                 strcpy(buf, "null");
459                 len = strlen(buf);
460         }
461
462         switch(usage & fileusage_TypeMask)
463         {
464                 case fileusage_Data:
465                         extension = ".glkdata";
466                         break;
467                 case fileusage_SavedGame:
468                         extension = ".glksave";
469                         break;
470                 case fileusage_InputRecord:
471                 case fileusage_Transcript:
472                         extension = ".txt";
473                         break;
474                 default:
475                         ILLEGAL_PARAM("Unknown file usage: %u", usage);
476                         return NULL;
477         }
478         filename = g_strconcat(buf, extension, NULL);
479         
480         /* Find out what encoding filenames are in */
481         const gchar **charsets; /* Do not free */
482         g_get_filename_charsets(&charsets);
483
484         /* Convert name to that encoding */
485         GError *error = NULL;
486         char *osname = g_convert(filename, -1, charsets[0], "ISO-8859-1", NULL, NULL, &error);
487         if(osname == NULL)
488         {
489                 WARNING_S("Error during latin1->filename conversion", error->message);
490                 return NULL;
491         }
492         
493         gchar *path;
494         if(glk_data->current_dir)
495                 path = g_build_filename(glk_data->current_dir, osname, NULL);
496         else
497                 path = g_strdup(osname);
498         g_free(osname);
499         
500         frefid_t f = fileref_new(path, buf, rock, usage, filemode_ReadWrite);
501         g_free(path);
502         g_free(buf);
503         return f;
504 }
505
506 /**
507  * glk_fileref_create_from_fileref:
508  * @usage: Bitfield with one or more of the <code>fileusage_</code> constants.
509  * @fref: Fileref to copy.
510  * @rock: The new fileref's rock value.
511  *
512  * This copies an existing file reference @fref, but changes the usage. (The
513  * original fileref is not modified.)
514  *
515  * The use of this function can be tricky. If you change the type of the fileref
516  * (%fileusage_Data, %fileusage_SavedGame, etc), the new reference may or may
517  * not point to the same actual disk file.
518  *
519  * <note><para>
520  *   Most platforms use suffixes to indicate file type, so it typically will
521  *   not. See the earlier comments about recommended file suffixes.
522  * </para></note>
523  *
524  * If you do this, and open both file references for writing, the results are
525  * unpredictable. It is safest to change the type of a fileref only if it refers
526  * to a nonexistent file.
527  *
528  * If you change the mode of a fileref (%fileusage_TextMode,
529  * %fileusage_BinaryMode), but leave the rest of the type unchanged, the new
530  * fileref will definitely point to the same disk file as the old one.
531  * 
532  * Obviously, if you write to a file in text mode and then read from it in
533  * binary mode, the results are platform-dependent. 
534  *
535  * Returns: A new fileref, or %NULL if the fileref creation failed. 
536  */
537 frefid_t
538 glk_fileref_create_from_fileref(glui32 usage, frefid_t fref, glui32 rock)
539 {
540         VALID_FILEREF(fref, return NULL);
541         return fileref_new(fref->filename, fref->basename, rock, usage, fref->orig_filemode);
542 }
543
544 /**
545  * glk_fileref_destroy:
546  * @fref: Fileref to destroy.
547  * 
548  * Destroys a fileref which you have created. This does <emphasis>not</emphasis>
549  * affect the disk file; it just reclaims the resources allocated by the
550  * <code>glk_fileref_create...</code> function.
551  *
552  * It is legal to destroy a fileref after opening a file with it (while the
553  * file is still open.) The fileref is only used for the opening operation,
554  * not for accessing the file stream.
555  */
556 void
557 glk_fileref_destroy(frefid_t fref)
558 {
559         VALID_FILEREF(fref, return);
560         fileref_close_common(fref);
561 }
562
563 /**
564  * glk_fileref_delete_file:
565  * @fref: A refrence to the file to delete.
566  *
567  * Deletes the file referred to by @fref. It does not destroy @fref itself.
568  *
569  * You should only call this with a fileref that refers to an existing file.
570  */
571 void
572 glk_fileref_delete_file(frefid_t fref)
573 {
574         VALID_FILEREF(fref, return);
575         if( glk_fileref_does_file_exist(fref) )
576         {
577                 if(g_unlink(fref->filename) == -1)
578                         IO_WARNING( "Error deleting file", fref->filename, g_strerror(errno) );
579         }
580         else
581         {
582                 ILLEGAL(_("Tried to delete a fileref that does not refer to an existing file."));
583         }
584
585 }
586
587 /**
588  * glk_fileref_does_file_exist:
589  * @fref: A fileref to check.
590  *
591  * Checks whether the file referred to by @fref exists.
592  *
593  * Returns: %TRUE (1) if @fref refers to an existing file, and %FALSE (0) if 
594  * not.
595  */
596 glui32
597 glk_fileref_does_file_exist(frefid_t fref)
598 {
599         VALID_FILEREF(fref, return 0);
600         if( g_file_test(fref->filename, G_FILE_TEST_EXISTS) )
601                 return 1;
602         return 0;
603 }
604