Pileus Git - ~andy/gtk/blob - gtk/gtkrecentmanager.c

   1 /* GTK - The GIMP Toolkit
   2  * gtkrecentmanager.c: a manager for the recently used resources
   3  *
   4  * Copyright (C) 2006 Emmanuele Bassi
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  */
  20
  21 #include "config.h"
  22
  23 #include <sys/types.h>
  24 #include <sys/stat.h>
  25 #ifdef HAVE_UNISTD_H
  26 #include <unistd.h>
  27 #endif
  28 #include <errno.h>
  29 #include <string.h>
  30 #include <stdlib.h>
  31 #include <glib.h>
  32 #include <glib/gstdio.h>
  33 #include <gio/gio.h>
  34
  35 #include "gtkrecentmanager.h"
  36 #include "gtkintl.h"
  37 #include "gtkstock.h"
  38 #include "gtkicontheme.h"
  39 #include "gtktypebuiltins.h"
  40 #include "gtkprivate.h"
  41 #include "gtkmarshalers.h"
  42 #include "gtkalias.h"
  43
  44 #ifdef G_OS_UNIX
  45 #define XDG_PREFIX _gtk_xdg
  46 #include "xdgmime/xdgmime.h"
  47 #endif
  48
  49 /* the file where we store the recently used items */
  50 #define GTK_RECENTLY_USED_FILE  ".recently-used.xbel"
  51
  52 /* return all items by default */
  53 #define DEFAULT_LIMIT   -1
  54
  55 /* keep in sync with xdgmime */
  56 #define GTK_RECENT_DEFAULT_MIME "application/octet-stream"
  57
  58 typedef struct
  59 {
  60   gchar *name;
  61   gchar *exec;
  62
  63   guint count;
  64
  65   time_t stamp;
  66 } RecentAppInfo;
  67
  68 struct _GtkRecentInfo
  69 {
  70   gchar *uri;
  71
  72   gchar *display_name;
  73   gchar *description;
  74
  75   time_t added;
  76   time_t modified;
  77   time_t visited;
  78
  79   gchar *mime_type;
  80
  81   GSList *applications;
  82   GHashTable *apps_lookup;
  83
  84   GSList *groups;
  85
  86   gboolean is_private;
  87
  88   GdkPixbuf *icon;
  89
  90   gint ref_count;
  91 };
  92
  93 #define GTK_RECENT_MANAGER_GET_PRIVATE(obj)     (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_RECENT_MANAGER, GtkRecentManagerPrivate))
  94
  95 struct _GtkRecentManagerPrivate
  96 {
  97   gchar *filename;
  98
  99   guint is_dirty : 1;
 100
 101   gint limit;
 102   gint size;
 103
 104   GBookmarkFile *recent_items;
 105
 106   GFileMonitor *monitor;
 107 };
 108
 109 enum
 110 {
 111   PROP_0,
 112
 113   PROP_FILENAME,
 114   PROP_LIMIT,
 115   PROP_SIZE
 116 };
 117
 118 static void     gtk_recent_manager_dispose                (GObject           *object);
 119 static void     gtk_recent_manager_finalize               (GObject           *object);
 120 static void     gtk_recent_manager_set_property           (GObject           *object,
 121                                                            guint              prop_id,
 122                                                            const GValue      *value,
 123                                                            GParamSpec        *pspec);
 124 static void     gtk_recent_manager_get_property           (GObject           *object,
 125                                                            guint              prop_id,
 126                                                            GValue            *value,
 127                                                            GParamSpec        *pspec);
 128 static void     gtk_recent_manager_add_item_query_info_cb (GObject           *source_object,
 129                                                            GAsyncResult      *res,
 130                                                            gpointer           user_data);
 131 static void     gtk_recent_manager_monitor_changed        (GFileMonitor      *monitor,
 132                                                            GFile             *file,
 133                                                            GFile             *other_file,
 134                                                            GFileMonitorEvent  event_type,
 135                                                            gpointer           user_data);
 136 static void     gtk_recent_manager_changed                (GtkRecentManager  *manager);
 137 static void     gtk_recent_manager_real_changed           (GtkRecentManager  *manager);
 138 static void     gtk_recent_manager_set_filename           (GtkRecentManager  *manager,
 139                                                            const gchar       *filename);
 140
 141 static void build_recent_items_list (GtkRecentManager  *manager);
 142 static void purge_recent_items_list (GtkRecentManager  *manager,
 143                                      GError           **error);
 144
 145 static RecentAppInfo *recent_app_info_new  (const gchar   *app_name);
 146 static void           recent_app_info_free (RecentAppInfo *app_info);
 147
 148 static GtkRecentInfo *gtk_recent_info_new  (const gchar   *uri);
 149 static void           gtk_recent_info_free (GtkRecentInfo *recent_info);
 150
 151 static guint signal_changed = 0;
 152
 153 static GtkRecentManager *recent_manager_singleton = NULL;
 154
 155 G_DEFINE_TYPE (GtkRecentManager, gtk_recent_manager, G_TYPE_OBJECT)
 156
 157 static void
 158 filename_warning (const gchar *format,
 159                   const gchar *filename,
 160                   const gchar *message)
 161 {
 162   gchar *utf8 = g_filename_to_utf8 (filename, -1, NULL, NULL, NULL);
 163   g_warning (format, utf8 ? utf8 : "(invalid filename)", message);
 164   g_free (utf8);
 165 }
 166
 167 /* Test of haystack has the needle prefix, comparing case
 168  * insensitive. haystack may be UTF-8, but needle must
 169  * contain only lowercase ascii. */
 170 static gboolean
 171 has_case_prefix (const gchar *haystack,
 172                  const gchar *needle)
 173 {
 174   const gchar *h, *n;
 175
 176   /* Eat one character at a time. */
 177   h = haystack;
 178   n = needle;
 179
 180   while (*n && *h && *n == g_ascii_tolower (*h))
 181     {
 182       n++;
 183       h++;
 184     }
 185
 186   return *n == '\0';
 187 }
 188
 189 GQuark
 190 gtk_recent_manager_error_quark (void)
 191 {
 192   return g_quark_from_static_string ("gtk-recent-manager-error-quark");
 193 }
 194
 195 static void
 196 gtk_recent_manager_class_init (GtkRecentManagerClass *klass)
 197 {
 198   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 199
 200   gobject_class->set_property = gtk_recent_manager_set_property;
 201   gobject_class->get_property = gtk_recent_manager_get_property;
 202   gobject_class->dispose = gtk_recent_manager_dispose;
 203   gobject_class->finalize = gtk_recent_manager_finalize;
 204
 205   /**
 206    * GtkRecentManager:filename
 207    *
 208    * The full path to the file to be used to store and read the recently
 209    * used resources list
 210    *
 211    * Since: 2.10
 212    */
 213   g_object_class_install_property (gobject_class,
 214                                    PROP_FILENAME,
 215                                    g_param_spec_string ("filename",
 216                                                         P_("Filename"),
 217                                                         P_("The full path to the file to be used to store and read the list"),
 218                                                         NULL,
 219                                                         (G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE)));
 220   /**
 221    * GtkRecentManager:limit
 222    *
 223    * The maximum number of items to be returned by the
 224    * gtk_recent_manager_get_items() function.
 225    *
 226    * Since: 2.10
 227    */
 228   g_object_class_install_property (gobject_class,
 229                                    PROP_LIMIT,
 230                                    g_param_spec_int ("limit",
 231                                                      P_("Limit"),
 232                                                      P_("The maximum number of items to be returned by gtk_recent_manager_get_items()"),
 233                                                      -1,
 234                                                      G_MAXINT,
 235                                                      DEFAULT_LIMIT,
 236                                                      G_PARAM_READWRITE));
 237   /**
 238    * GtkRecentManager:size
 239    *
 240    * The size of the recently used resources list.
 241    *
 242    * Since: 2.10
 243    */
 244   g_object_class_install_property (gobject_class,
 245                                    PROP_SIZE,
 246                                    g_param_spec_int ("size",
 247                                                      P_("Size"),
 248                                                      P_("The size of the recently used resources list"),
 249                                                      -1,
 250                                                      G_MAXINT,
 251                                                      0,
 252                                                      G_PARAM_READABLE));
 253
 254   /**
 255    * GtkRecentManager::changed
 256    * @recent_manager: the recent manager
 257    *
 258    * Emitted when the current recently used resources manager changes its
 259    * contents.
 260    *
 261    * Since: 2.10
 262    */
 263   signal_changed =
 264     g_signal_new (I_("changed"),
 265                   G_TYPE_FROM_CLASS (klass),
 266                   G_SIGNAL_RUN_FIRST,
 267                   G_STRUCT_OFFSET (GtkRecentManagerClass, changed),
 268                   NULL, NULL,
 269                   g_cclosure_marshal_VOID__VOID,
 270                   G_TYPE_NONE, 0);
 271
 272   klass->changed = gtk_recent_manager_real_changed;
 273
 274   g_type_class_add_private (klass, sizeof (GtkRecentManagerPrivate));
 275 }
 276
 277 static void
 278 gtk_recent_manager_init (GtkRecentManager *manager)
 279 {
 280   GtkRecentManagerPrivate *priv;
 281   gchar *filename;
 282
 283   manager->priv = priv = GTK_RECENT_MANAGER_GET_PRIVATE (manager);
 284
 285   priv->limit = DEFAULT_LIMIT;
 286   priv->size = 0;
 287
 288   /* this will take care of building the files list */
 289   filename = g_build_filename (g_get_home_dir (),
 290                                GTK_RECENTLY_USED_FILE,
 291                                NULL);
 292   gtk_recent_manager_set_filename (manager, filename);
 293   g_free (filename);
 294 }
 295
 296 static void
 297 gtk_recent_manager_set_property (GObject               *object,
 298                                  guint                  prop_id,
 299                                  const GValue          *value,
 300                                  GParamSpec            *pspec)
 301 {
 302   GtkRecentManager *recent_manager = GTK_RECENT_MANAGER (object);
 303
 304   switch (prop_id)
 305     {
 306     case PROP_FILENAME:
 307       gtk_recent_manager_set_filename (recent_manager, g_value_get_string (value));
 308       break;
 309     case PROP_LIMIT:
 310       gtk_recent_manager_set_limit (recent_manager, g_value_get_int (value));
 311       break;
 312     default:
 313       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 314       break;
 315     }
 316 }
 317
 318 static void
 319 gtk_recent_manager_get_property (GObject               *object,
 320                                  guint                  prop_id,
 321                                  GValue                *value,
 322                                  GParamSpec            *pspec)
 323 {
 324   GtkRecentManager *recent_manager = GTK_RECENT_MANAGER (object);
 325
 326   switch (prop_id)
 327     {
 328     case PROP_FILENAME:
 329       g_value_set_string (value, recent_manager->priv->filename);
 330       break;
 331     case PROP_LIMIT:
 332       g_value_set_int (value, recent_manager->priv->limit);
 333       break;
 334     case PROP_SIZE:
 335       g_value_set_int (value, recent_manager->priv->size);
 336       break;
 337     default:
 338       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 339       break;
 340     }
 341 }
 342
 343 static void
 344 gtk_recent_manager_dispose (GObject *object)
 345 {
 346   GtkRecentManager *manager = GTK_RECENT_MANAGER (object);
 347   GtkRecentManagerPrivate *priv = manager->priv;
 348
 349   if (priv->monitor)
 350     {
 351       g_signal_handlers_disconnect_by_func (priv->monitor,
 352                                             G_CALLBACK (gtk_recent_manager_monitor_changed),
 353                                             manager);
 354       g_object_unref (priv->monitor);
 355       priv->monitor = NULL;
 356     }
 357
 358   G_OBJECT_CLASS (gtk_recent_manager_parent_class)->dispose (object);
 359 }
 360
 361 static void
 362 gtk_recent_manager_finalize (GObject *object)
 363 {
 364   GtkRecentManager *manager = GTK_RECENT_MANAGER (object);
 365   GtkRecentManagerPrivate *priv = manager->priv;
 366
 367   g_free (priv->filename);
 368
 369   if (priv->recent_items)
 370     g_bookmark_file_free (priv->recent_items);
 371
 372   G_OBJECT_CLASS (gtk_recent_manager_parent_class)->finalize (object);
 373 }
 374
 375 static void
 376 gtk_recent_manager_real_changed (GtkRecentManager *manager)
 377 {
 378   GtkRecentManagerPrivate *priv = manager->priv;
 379
 380   g_object_freeze_notify (G_OBJECT (manager));
 381
 382   if (priv->is_dirty)
 383     {
 384       GError *write_error;
 385
 386       /* we are marked as dirty, so we dump the content of our
 387        * recently used items list
 388        */
 389       g_assert (priv->filename != NULL);
 390
 391       /* if no container object has been defined, we create a new
 392        * empty container, and dump it
 393        */
 394       if (!priv->recent_items)
 395         {
 396           priv->recent_items = g_bookmark_file_new ();
 397           priv->size = 0;
 398         }
 399
 400       write_error = NULL;
 401       g_bookmark_file_to_file (priv->recent_items, priv->filename, &write_error);
 402       if (write_error)
 403         {
 404           filename_warning ("Attempting to store changes into `%s', "
 405                             "but failed: %s",
 406                             priv->filename,
 407                             write_error->message);
 408           g_error_free (write_error);
 409         }
 410
 411       /* mark us as clean */
 412       priv->is_dirty = FALSE;
 413     }
 414   else
 415     {
 416       /* we are not marked as dirty, so we have been called
 417        * because the recently used resources file has been
 418        * changed (and not from us).
 419        */
 420       build_recent_items_list (manager);
 421     }
 422
 423   g_object_thaw_notify (G_OBJECT (manager));
 424 }
 425
 426 static void
 427 gtk_recent_manager_monitor_changed (GFileMonitor      *monitor,
 428                                     GFile             *file,
 429                                     GFile             *other_file,
 430                                     GFileMonitorEvent  event_type,
 431                                     gpointer           user_data)
 432 {
 433   GtkRecentManager *manager = user_data;
 434
 435   switch (event_type)
 436     {
 437     case G_FILE_MONITOR_EVENT_CHANGED:
 438     case G_FILE_MONITOR_EVENT_CREATED:
 439       gtk_recent_manager_changed (manager);
 440       break;
 441
 442     case G_FILE_MONITOR_EVENT_DELETED:
 443       break;
 444
 445     default:
 446       break;
 447     }
 448 }
 449
 450 static void
 451 gtk_recent_manager_set_filename (GtkRecentManager *manager,
 452                                  const gchar      *filename)
 453 {
 454   GtkRecentManagerPrivate *priv;
 455   GFile *file;
 456   GError *error;
 457
 458   g_assert (GTK_IS_RECENT_MANAGER (manager));
 459
 460   priv = manager->priv;
 461
 462   g_free (priv->filename);
 463
 464   if (priv->monitor)
 465     {
 466       g_signal_handlers_disconnect_by_func (priv->monitor,
 467                                             G_CALLBACK (gtk_recent_manager_monitor_changed),
 468                                             manager);
 469       g_object_unref (priv->monitor);
 470       priv->monitor = NULL;
 471     }
 472
 473   if (!filename || filename[0] == '\0')
 474     return;
 475
 476   priv->filename = g_strdup (filename);
 477   file = g_file_new_for_path (priv->filename);
 478
 479   error = NULL;
 480   priv->monitor = g_file_monitor_file (file, G_FILE_MONITOR_NONE, NULL, &error);
 481   if (error)
 482     {
 483       filename_warning ("Unable to monitor `%s': %s\n"
 484                         "The GtkRecentManager will not update its contents "
 485                         "if the file is changed from other instances",
 486                         priv->filename,
 487                         error->message);
 488       g_error_free (error);
 489     }
 490   else
 491     g_signal_connect (priv->monitor, "changed",
 492                       G_CALLBACK (gtk_recent_manager_monitor_changed),
 493                       manager);
 494
 495   g_object_unref (file);
 496
 497   priv->is_dirty = FALSE;
 498   build_recent_items_list (manager);
 499 }
 500
 501 /* reads the recently used resources file and builds the items list.
 502  * we keep the items list inside the parser object, and build the
 503  * RecentInfo object only on user's demand to avoid useless replication.
 504  * this function resets the dirty bit of the manager.
 505  */
 506 static void
 507 build_recent_items_list (GtkRecentManager *manager)
 508 {
 509   GtkRecentManagerPrivate *priv = manager->priv;
 510   GError *read_error;
 511   gint size;
 512
 513   g_assert (priv->filename != NULL);
 514
 515   if (!priv->recent_items)
 516     {
 517       priv->recent_items = g_bookmark_file_new ();
 518       priv->size = 0;
 519     }
 520
 521   /* the file exists, and it's valid (we hope); if not, destroy the container
 522    * object and hope for a better result when the next "changed" signal is
 523    * fired. */
 524   read_error = NULL;
 525   g_bookmark_file_load_from_file (priv->recent_items, priv->filename, &read_error);
 526   if (read_error)
 527     {
 528       /* if the file does not exist we just wait for the first write
 529        * operation on this recent manager instance, to avoid creating
 530        * empty files and leading to spurious file system events (Sabayon
 531        * will not be happy about those)
 532        */
 533       if (read_error->domain == G_FILE_ERROR &&
 534           read_error->code != G_FILE_ERROR_NOENT)
 535         filename_warning ("Attempting to read the recently used resources "
 536                           "file at `%s', but the parser failed: %s.",
 537                           priv->filename,
 538                           read_error->message);
 539
 540       g_bookmark_file_free (priv->recent_items);
 541       priv->recent_items = NULL;
 542
 543       g_error_free (read_error);
 544     }
 545   else
 546     {
 547       size = g_bookmark_file_get_size (priv->recent_items);
 548       if (priv->size != size)
 549         {
 550           priv->size = size;
 551
 552           g_object_notify (G_OBJECT (manager), "size");
 553         }
 554     }
 555
 556   priv->is_dirty = FALSE;
 557 }
 558
 559
 560 /********************
 561  * GtkRecentManager *
 562  ********************/
 563
 564
 565 /**
 566  * gtk_recent_manager_new:
 567  *
 568  * Creates a new recent manager object.  Recent manager objects are used to
 569  * handle the list of recently used resources.  A #GtkRecentManager object
 570  * monitors the recently used resources list, and emits the "changed" signal
 571  * each time something inside the list changes.
 572  *
 573  * #GtkRecentManager objects are expensive: be sure to create them only when
 574  * needed. You should use gtk_recent_manager_get_default() instead.
 575  *
 576  * Return value: A newly created #GtkRecentManager object.
 577  *
 578  * Since: 2.10
 579  */
 580 GtkRecentManager *
 581 gtk_recent_manager_new (void)
 582 {
 583   return g_object_new (GTK_TYPE_RECENT_MANAGER, NULL);
 584 }
 585
 586 /**
 587  * gtk_recent_manager_get_default:
 588  *
 589  * Gets a unique instance of #GtkRecentManager, that you can share
 590  * in your application without caring about memory management. The
 591  * returned instance will be freed when you application terminates.
 592  *
 593  * Return value: A unique #GtkRecentManager. Do not ref or unref it.
 594  *
 595  * Since: 2.10
 596  */
 597 GtkRecentManager *
 598 gtk_recent_manager_get_default (void)
 599 {
 600   if (G_UNLIKELY (!recent_manager_singleton))
 601     recent_manager_singleton = gtk_recent_manager_new ();
 602
 603   return recent_manager_singleton;
 604 }
 605
 606 /**
 607  * gtk_recent_manager_get_for_screen:
 608  * @screen: a #GdkScreen
 609  *
 610  * Gets the recent manager object associated with @screen; if this
 611  * function has not previously been called for the given screen,
 612  * a new recent manager object will be created and associated with
 613  * the screen. Recent manager objects are fairly expensive to create,
 614  * so using this function is usually a better choice than calling
 615  * gtk_recent_manager_new() and setting the screen yourself; by using
 616  * this function a single recent manager object will be shared between
 617  * users.
 618  *
 619  * Return value: A unique #GtkRecentManager associated with the given
 620  *   screen. This recent manager is associated to the with the screen
 621  *   and can be used as long as the screen is open. Do not ref or
 622  *   unref it.
 623  *
 624  * Deprecated: 2.12: This function has been deprecated and should
 625  *   not be used in newly written code. Calling this function is
 626  *   equivalent to calling gtk_recent_manager_get_default().
 627  *
 628  * Since: 2.10
 629  */
 630 GtkRecentManager *
 631 gtk_recent_manager_get_for_screen (GdkScreen *screen)
 632 {
 633   return gtk_recent_manager_get_default ();
 634 }
 635
 636 /**
 637  * gtk_recent_manager_set_screen:
 638  * @manager: a #GtkRecentManager
 639  * @screen: a #GdkScreen
 640  *
 641  * Sets the screen for a recent manager; the screen is used to
 642  * track the user's currently configured recently used documents
 643  * storage.
 644  *
 645  * Since: 2.10
 646  *
 647  * Deprecated: 2.12: This function has been deprecated and should
 648  *   not be used in newly written code. Calling this function has
 649  *   no effect.
 650  */
 651 void
 652 gtk_recent_manager_set_screen (GtkRecentManager *manager,
 653                                GdkScreen        *screen)
 654 {
 655
 656 }
 657
 658 /**
 659  * gtk_recent_manager_set_limit:
 660  * @manager: a #GtkRecentManager
 661  * @limit: the maximum number of items to return, or -1.
 662  *
 663  * Sets the maximum number of item that the gtk_recent_manager_get_items()
 664  * function should return.  If @limit is set to -1, then return all the
 665  * items.
 666  *
 667  * Since: 2.10
 668  */
 669 void
 670 gtk_recent_manager_set_limit (GtkRecentManager *manager,
 671                               gint              limit)
 672 {
 673   GtkRecentManagerPrivate *priv;
 674
 675   g_return_if_fail (GTK_IS_RECENT_MANAGER (manager));
 676
 677   priv = manager->priv;
 678   priv->limit = limit;
 679 }
 680
 681 /**
 682  * gtk_recent_manager_get_limit:
 683  * @manager: a #GtkRecentManager
 684  *
 685  * Gets the maximum number of items that the gtk_recent_manager_get_items()
 686  * function should return.
 687  *
 688  * Return value: the number of items to return, or -1 for every item.
 689  *
 690  * Since: 2.10
 691  */
 692 gint
 693 gtk_recent_manager_get_limit (GtkRecentManager *manager)
 694 {
 695   GtkRecentManagerPrivate *priv;
 696
 697   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), DEFAULT_LIMIT);
 698
 699   priv = manager->priv;
 700   return priv->limit;
 701 }
 702
 703 static void
 704 gtk_recent_manager_add_item_query_info_cb (GObject      *source_object,
 705                                            GAsyncResult *res,
 706                                            gpointer      user_data)
 707 {
 708   GFile *file = G_FILE (source_object);
 709   GtkRecentManager *manager = user_data;
 710   GtkRecentData recent_data;
 711   GFileInfo *file_info;
 712   gchar *uri;
 713   GError *error;
 714
 715   uri = g_file_get_uri (file);
 716
 717   error = NULL;
 718   file_info = g_file_query_info_finish (file, res, &error);
 719   if (error)
 720     {
 721       g_warning ("Unable to retrieve the file info for `%s': %s",
 722                  uri,
 723                  error->message);
 724       g_error_free (error);
 725       goto out;
 726     }
 727
 728   recent_data.display_name = NULL;
 729   recent_data.description = NULL;
 730
 731   if (file_info)
 732     {
 733       recent_data.mime_type = g_content_type_get_mime_type (g_file_info_get_content_type (file_info));
 734       g_object_unref (file_info);
 735     }
 736   else
 737     recent_data.mime_type = g_strdup (GTK_RECENT_DEFAULT_MIME);
 738
 739   recent_data.app_name = g_strdup (g_get_application_name ());
 740   recent_data.app_exec = g_strjoin (" ", g_get_prgname (), "%u", NULL);
 741   recent_data.groups = NULL;
 742   recent_data.is_private = FALSE;
 743
 744   /* Ignore return value, this can't fail anyway since all required
 745    * fields are set */
 746   gtk_recent_manager_add_full (manager, uri, &recent_data);
 747
 748   g_free (recent_data.mime_type);
 749   g_free (recent_data.app_name);
 750   g_free (recent_data.app_exec);
 751
 752 out:
 753   g_object_unref (manager);
 754   g_free (uri);
 755 }
 756
 757 /**
 758  * gtk_recent_manager_add_item:
 759  * @manager: a #GtkRecentManager
 760  * @uri: a valid URI
 761  *
 762  * Adds a new resource, pointed by @uri, into the recently used
 763  * resources list.
 764  *
 765  * This function automatically retrieves some of the needed
 766  * metadata and setting other metadata to common default values; it
 767  * then feeds the data to gtk_recent_manager_add_full().
 768  *
 769  * See gtk_recent_manager_add_full() if you want to explicitly
 770  * define the metadata for the resource pointed by @uri.
 771  *
 772  * Return value: %TRUE if the new item was successfully added
 773  *   to the recently used resources list
 774  *
 775  * Since: 2.10
 776  */
 777 gboolean
 778 gtk_recent_manager_add_item (GtkRecentManager  *manager,
 779                              const gchar       *uri)
 780 {
 781   GFile* file;
 782
 783   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), FALSE);
 784   g_return_val_if_fail (uri != NULL, FALSE);
 785
 786   file = g_file_new_for_uri (uri);
 787
 788   g_file_query_info_async (file,
 789                            G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE,
 790                            G_PRIORITY_DEFAULT,
 791                            G_FILE_QUERY_INFO_NONE,
 792                            NULL,
 793                            gtk_recent_manager_add_item_query_info_cb,
 794                            g_object_ref (manager));
 795
 796   g_object_unref (file);
 797
 798   return TRUE;
 799 }
 800
 801 /**
 802  * gtk_recent_manager_add_full:
 803  * @manager: a #GtkRecentManager
 804  * @uri: a valid URI
 805  * @recent_data: metadata of the resource
 806  *
 807  * Adds a new resource, pointed by @uri, into the recently used
 808  * resources list, using the metadata specified inside the #GtkRecentData
 809  * structure passed in @recent_data.
 810  *
 811  * The passed URI will be used to identify this resource inside the
 812  * list.
 813  *
 814  * In order to register the new recently used resource, metadata about
 815  * the resource must be passed as well as the URI; the metadata is
 816  * stored in a #GtkRecentData structure, which must contain the MIME
 817  * type of the resource pointed by the URI; the name of the application
 818  * that is registering the item, and a command line to be used when
 819  * launching the item.
 820  *
 821  * Optionally, a #GtkRecentData structure might contain a UTF-8 string
 822  * to be used when viewing the item instead of the last component of the
 823  * URI; a short description of the item; whether the item should be
 824  * considered private - that is, should be displayed only by the
 825  * applications that have registered it.
 826  *
 827  * Return value: %TRUE if the new item was successfully added to the
 828  * recently used resources list, %FALSE otherwise.
 829  *
 830  * Since: 2.10
 831  */
 832 gboolean
 833 gtk_recent_manager_add_full (GtkRecentManager     *manager,
 834                              const gchar          *uri,
 835                              const GtkRecentData  *data)
 836 {
 837   GtkRecentManagerPrivate *priv;
 838
 839   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), FALSE);
 840   g_return_val_if_fail (uri != NULL, FALSE);
 841   g_return_val_if_fail (data != NULL, FALSE);
 842
 843   /* sanity checks */
 844   if ((data->display_name) &&
 845       (!g_utf8_validate (data->display_name, -1, NULL)))
 846     {
 847       g_warning ("Attempting to add `%s' to the list of recently used "
 848                  "resources, but the display name is not a valid UTF-8 "
 849                  "encoded string",
 850                  uri);
 851       return FALSE;
 852     }
 853
 854   if ((data->description) &&
 855       (!g_utf8_validate (data->description, -1, NULL)))
 856     {
 857       g_warning ("Attempting to add `%s' to the list of recently used "
 858                  "resources, but the description is not a valid UTF-8 "
 859                  "encoded string",
 860                  uri);
 861       return FALSE;
 862     }
 863
 864
 865   if (!data->mime_type)
 866     {
 867       g_warning ("Attempting to add `%s' to the list of recently used "
 868                  "resources, but not MIME type was defined",
 869                  uri);
 870       return FALSE;
 871     }
 872
 873   if (!data->app_name)
 874     {
 875       g_warning ("Attempting to add `%s' to the list of recently used "
 876                  "resources, but no name of the application that is "
 877                  "registering it was defined",
 878                  uri);
 879       return FALSE;
 880     }
 881
 882   if (!data->app_exec)
 883     {
 884       g_warning ("Attempting to add `%s' to the list of recently used "
 885                  "resources, but no command line for the application "
 886                  "that is registering it was defined",
 887                  uri);
 888       return FALSE;
 889     }
 890
 891   priv = manager->priv;
 892
 893   if (!priv->recent_items)
 894     {
 895       priv->recent_items = g_bookmark_file_new ();
 896       priv->size = 0;
 897     }
 898
 899   if (data->display_name)
 900     g_bookmark_file_set_title (priv->recent_items, uri, data->display_name);
 901
 902   if (data->description)
 903     g_bookmark_file_set_description (priv->recent_items, uri, data->description);
 904
 905   g_bookmark_file_set_mime_type (priv->recent_items, uri, data->mime_type);
 906
 907   if (data->groups && data->groups[0] != '\0')
 908     {
 909       gint j;
 910
 911       for (j = 0; (data->groups)[j] != NULL; j++)
 912         g_bookmark_file_add_group (priv->recent_items, uri, (data->groups)[j]);
 913     }
 914
 915   /* register the application; this will take care of updating the
 916    * registration count and time in case the application has
 917    * already registered the same document inside the list
 918    */
 919   g_bookmark_file_add_application (priv->recent_items, uri,
 920                                    data->app_name,
 921                                    data->app_exec);
 922
 923   g_bookmark_file_set_is_private (priv->recent_items, uri,
 924                                   data->is_private);
 925
 926   /* mark us as dirty, so that when emitting the "changed" signal we
 927    * will dump our changes
 928    */
 929   priv->is_dirty = TRUE;
 930
 931   gtk_recent_manager_changed (manager);
 932
 933   return TRUE;
 934 }
 935
 936 /**
 937  * gtk_recent_manager_remove_item:
 938  * @manager: a #GtkRecentManager
 939  * @uri: the URI of the item you wish to remove
 940  * @error: return location for a #GError, or %NULL
 941  *
 942  * Removes a resource pointed by @uri from the recently used resources
 943  * list handled by a recent manager.
 944  *
 945  * Return value: %TRUE if the item pointed by @uri has been successfully
 946  *   removed by the recently used resources list, and %FALSE otherwise.
 947  *
 948  * Since: 2.10
 949  */
 950 gboolean
 951 gtk_recent_manager_remove_item (GtkRecentManager  *manager,
 952                                 const gchar       *uri,
 953                                 GError           **error)
 954 {
 955   GtkRecentManagerPrivate *priv;
 956   GError *remove_error = NULL;
 957
 958   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), FALSE);
 959   g_return_val_if_fail (uri != NULL, FALSE);
 960   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 961
 962   priv = manager->priv;
 963
 964   if (!priv->recent_items)
 965     {
 966       priv->recent_items = g_bookmark_file_new ();
 967       priv->size = 0;
 968
 969       g_set_error (error, GTK_RECENT_MANAGER_ERROR,
 970                    GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
 971                    _("Unable to find an item with URI '%s'"),
 972                    uri);
 973
 974       return FALSE;
 975     }
 976
 977   g_bookmark_file_remove_item (priv->recent_items, uri, &remove_error);
 978   if (remove_error)
 979     {
 980       g_propagate_error (error, remove_error);
 981
 982       return FALSE;
 983     }
 984
 985   priv->is_dirty = TRUE;
 986
 987   gtk_recent_manager_changed (manager);
 988
 989   return TRUE;
 990 }
 991
 992 /**
 993  * gtk_recent_manager_has_item:
 994  * @manager: a #GtkRecentManager
 995  * @uri: a URI
 996  *
 997  * Checks whether there is a recently used resource registered
 998  * with @uri inside the recent manager.
 999  *
1000  * Return value: %TRUE if the resource was found, %FALSE otherwise.
1001  *
1002  * Since: 2.10
1003  */
1004 gboolean
1005 gtk_recent_manager_has_item (GtkRecentManager *manager,
1006                              const gchar      *uri)
1007 {
1008   GtkRecentManagerPrivate *priv;
1009
1010   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), FALSE);
1011   g_return_val_if_fail (uri != NULL, FALSE);
1012
1013   priv = manager->priv;
1014   g_return_val_if_fail (priv->recent_items != NULL, FALSE);
1015
1016   return g_bookmark_file_has_item (priv->recent_items, uri);
1017 }
1018
1019 static void
1020 build_recent_info (GBookmarkFile  *bookmarks,
1021                    GtkRecentInfo  *info)
1022 {
1023   gchar **apps, **groups;
1024   gsize apps_len, groups_len, i;
1025
1026   g_assert (bookmarks != NULL);
1027   g_assert (info != NULL);
1028
1029   info->display_name = g_bookmark_file_get_title (bookmarks, info->uri, NULL);
1030   info->description = g_bookmark_file_get_description (bookmarks, info->uri, NULL);
1031   info->mime_type = g_bookmark_file_get_mime_type (bookmarks, info->uri, NULL);
1032
1033   info->is_private = g_bookmark_file_get_is_private (bookmarks, info->uri, NULL);
1034
1035   info->added = g_bookmark_file_get_added (bookmarks, info->uri, NULL);
1036   info->modified = g_bookmark_file_get_modified (bookmarks, info->uri, NULL);
1037   info->visited = g_bookmark_file_get_visited (bookmarks, info->uri, NULL);
1038
1039   groups = g_bookmark_file_get_groups (bookmarks, info->uri, &groups_len, NULL);
1040   for (i = 0; i < groups_len; i++)
1041     {
1042       gchar *group_name = g_strdup (groups[i]);
1043
1044       info->groups = g_slist_append (info->groups, group_name);
1045     }
1046
1047   g_strfreev (groups);
1048
1049   apps = g_bookmark_file_get_applications (bookmarks, info->uri, &apps_len, NULL);
1050   for (i = 0; i < apps_len; i++)
1051     {
1052       gchar *app_name, *app_exec;
1053       guint count;
1054       time_t stamp;
1055       RecentAppInfo *app_info;
1056       gboolean res;
1057
1058       app_name = apps[i];
1059
1060       res = g_bookmark_file_get_app_info (bookmarks, info->uri, app_name,
1061                                           &app_exec,
1062                                           &count,
1063                                           &stamp,
1064                                           NULL);
1065       if (!res)
1066         continue;
1067
1068       app_info = recent_app_info_new (app_name);
1069       app_info->exec = app_exec;
1070       app_info->count = count;
1071       app_info->stamp = stamp;
1072
1073       info->applications = g_slist_prepend (info->applications, app_info);
1074       g_hash_table_replace (info->apps_lookup, app_info->name, app_info);
1075     }
1076
1077   g_strfreev (apps);
1078 }
1079
1080 /**
1081  * gtk_recent_manager_lookup_item:
1082  * @manager: a #GtkRecentManager
1083  * @uri: a URI
1084  * @error: a return location for a #GError, or %NULL
1085  *
1086  * Searches for a URI inside the recently used resources list, and
1087  * returns a structure containing informations about the resource
1088  * like its MIME type, or its display name.
1089  *
1090  * Return value: a #GtkRecentInfo structure containing information
1091  *   about the resource pointed by @uri, or %NULL if the URI was
1092  *   not registered in the recently used resources list.  Free with
1093  *   gtk_recent_info_unref().
1094  *
1095  * Since: 2.10
1096  */
1097 GtkRecentInfo *
1098 gtk_recent_manager_lookup_item (GtkRecentManager  *manager,
1099                                 const gchar       *uri,
1100                                 GError           **error)
1101 {
1102   GtkRecentManagerPrivate *priv;
1103   GtkRecentInfo *info = NULL;
1104
1105   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), NULL);
1106   g_return_val_if_fail (uri != NULL, NULL);
1107   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1108
1109   priv = manager->priv;
1110   if (!priv->recent_items)
1111     {
1112       priv->recent_items = g_bookmark_file_new ();
1113       priv->size = 0;
1114
1115       g_set_error (error, GTK_RECENT_MANAGER_ERROR,
1116                    GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
1117                    _("Unable to find an item with URI '%s'"),
1118                    uri);
1119
1120       return NULL;
1121     }
1122
1123   if (!g_bookmark_file_has_item (priv->recent_items, uri))
1124     {
1125       g_set_error (error, GTK_RECENT_MANAGER_ERROR,
1126                    GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
1127                    _("Unable to find an item with URI '%s'"),
1128                    uri);
1129       return NULL;
1130     }
1131
1132   info = gtk_recent_info_new (uri);
1133   g_return_val_if_fail (info != NULL, NULL);
1134
1135   /* fill the RecentInfo structure with the data retrieved by our
1136    * parser object from the storage file
1137    */
1138   build_recent_info (priv->recent_items, info);
1139
1140   return info;
1141 }
1142
1143 /**
1144  * gtk_recent_manager_move_item:
1145  * @manager: a #GtkRecentManager
1146  * @uri: the URI of a recently used resource
1147  * @new_uri: the new URI of the recently used resource, or %NULL to
1148  *    remove the item pointed by @uri in the list
1149  * @error: a return location for a #GError, or %NULL
1150  *
1151  * Changes the location of a recently used resource from @uri to @new_uri.
1152  *
1153  * Please note that this function will not affect the resource pointed
1154  * by the URIs, but only the URI used in the recently used resources list.
1155  *
1156  * Return value: %TRUE on success.
1157  *
1158  * Since: 2.10
1159  */
1160 gboolean
1161 gtk_recent_manager_move_item (GtkRecentManager  *recent_manager,
1162                               const gchar       *uri,
1163                               const gchar       *new_uri,
1164                               GError           **error)
1165 {
1166   GtkRecentManagerPrivate *priv;
1167   GError *move_error;
1168   gboolean res;
1169
1170   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (recent_manager), FALSE);
1171   g_return_val_if_fail (uri != NULL, FALSE);
1172   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1173
1174   priv = recent_manager->priv;
1175
1176   if (!g_bookmark_file_has_item (priv->recent_items, uri))
1177     {
1178       g_set_error (error, GTK_RECENT_MANAGER_ERROR,
1179                    GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
1180                    _("Unable to find an item with URI '%s'"),
1181                    uri);
1182       return FALSE;
1183     }
1184
1185   move_error = NULL;
1186   res = g_bookmark_file_move_item (priv->recent_items,
1187                                    uri, new_uri,
1188                                    &move_error);
1189   if (move_error)
1190     {
1191       g_propagate_error (error, move_error);
1192       return FALSE;
1193     }
1194
1195   priv->is_dirty = TRUE;
1196
1197   gtk_recent_manager_changed (recent_manager);
1198
1199   return TRUE;
1200 }
1201
1202 /**
1203  * gtk_recent_manager_get_items:
1204  * @manager: a #GtkRecentManager
1205  *
1206  * Gets the list of recently used resources.
1207  *
1208  * Return value: a list of newly allocated #GtkRecentInfo objects. Use
1209  *   gtk_recent_info_unref() on each item inside the list, and then
1210  *   free the list itself using g_list_free().
1211  *
1212  * Since: 2.10
1213  */
1214 GList *
1215 gtk_recent_manager_get_items (GtkRecentManager *manager)
1216 {
1217   GtkRecentManagerPrivate *priv;
1218   GList *retval = NULL;
1219   gchar **uris;
1220   gsize uris_len, i;
1221
1222   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), NULL);
1223
1224   priv = manager->priv;
1225   if (!priv->recent_items)
1226     return NULL;
1227
1228   if (priv->limit == 0)
1229     return NULL;
1230
1231   uris = g_bookmark_file_get_uris (priv->recent_items, &uris_len);
1232   for (i = 0; i < uris_len; i++)
1233     {
1234       GtkRecentInfo *info;
1235
1236       if (priv->limit != -1 && i == priv->limit)
1237         break;
1238
1239       info = gtk_recent_info_new (uris[i]);
1240       build_recent_info (priv->recent_items, info);
1241
1242       retval = g_list_prepend (retval, info);
1243     }
1244
1245   g_strfreev (uris);
1246
1247   return retval;
1248 }
1249
1250 static void
1251 purge_recent_items_list (GtkRecentManager  *manager,
1252                          GError           **error)
1253 {
1254   GtkRecentManagerPrivate *priv = manager->priv;
1255
1256   if (!priv->recent_items)
1257     return;
1258
1259   g_bookmark_file_free (priv->recent_items);
1260   priv->recent_items = NULL;
1261
1262   priv->recent_items = g_bookmark_file_new ();
1263   priv->size = 0;
1264   priv->is_dirty = TRUE;
1265
1266   /* emit the changed signal, to ensure that the purge is written */
1267   gtk_recent_manager_changed (manager);
1268 }
1269
1270 /**
1271  * gtk_recent_manager_purge_items:
1272  * @manager: a #GtkRecentManager
1273  * @error: a return location for a #GError, or %NULL
1274  *
1275  * Purges every item from the recently used resources list.
1276  *
1277  * Return value: the number of items that have been removed from the
1278  *   recently used resources list.
1279  *
1280  * Since: 2.10
1281  */
1282 gint
1283 gtk_recent_manager_purge_items (GtkRecentManager  *manager,
1284                                 GError           **error)
1285 {
1286   GtkRecentManagerPrivate *priv;
1287   gint count, purged;
1288
1289   g_return_val_if_fail (GTK_IS_RECENT_MANAGER (manager), -1);
1290
1291   priv = manager->priv;
1292   if (!priv->recent_items)
1293     return 0;
1294
1295   count = g_bookmark_file_get_size (priv->recent_items);
1296   if (!count)
1297     return 0;
1298
1299   purge_recent_items_list (manager, error);
1300
1301   purged = count - g_bookmark_file_get_size (priv->recent_items);
1302
1303   return purged;
1304 }
1305
1306 static void
1307 gtk_recent_manager_changed (GtkRecentManager *recent_manager)
1308 {
1309   g_signal_emit (recent_manager, signal_changed, 0);
1310 }
1311
1312 /*****************
1313  * GtkRecentInfo *
1314  *****************/
1315
1316 GType
1317 gtk_recent_info_get_type (void)
1318 {
1319   static GType info_type = 0;
1320
1321   if (!info_type)
1322     info_type = g_boxed_type_register_static (I_("GtkRecentInfo"),
1323                                               (GBoxedCopyFunc) gtk_recent_info_ref,
1324                                               (GBoxedFreeFunc) gtk_recent_info_unref);
1325   return info_type;
1326 }
1327
1328 static GtkRecentInfo *
1329 gtk_recent_info_new (const gchar *uri)
1330 {
1331   GtkRecentInfo *info;
1332
1333   g_assert (uri != NULL);
1334
1335   info = g_new0 (GtkRecentInfo, 1);
1336   info->uri = g_strdup (uri);
1337
1338   info->applications = NULL;
1339   info->apps_lookup = g_hash_table_new (g_str_hash, g_str_equal);
1340
1341   info->groups = NULL;
1342
1343   info->ref_count = 1;
1344
1345   return info;
1346 }
1347
1348 static void
1349 gtk_recent_info_free (GtkRecentInfo *recent_info)
1350 {
1351   if (!recent_info)
1352     return;
1353
1354   g_free (recent_info->uri);
1355   g_free (recent_info->display_name);
1356   g_free (recent_info->description);
1357   g_free (recent_info->mime_type);
1358
1359   if (recent_info->applications)
1360     {
1361       g_slist_foreach (recent_info->applications,
1362                        (GFunc) recent_app_info_free,
1363                        NULL);
1364       g_slist_free (recent_info->applications);
1365
1366       recent_info->applications = NULL;
1367     }
1368
1369   if (recent_info->apps_lookup)
1370     g_hash_table_destroy (recent_info->apps_lookup);
1371
1372   if (recent_info->groups)
1373     {
1374       g_slist_foreach (recent_info->groups,
1375                        (GFunc) g_free,
1376                        NULL);
1377       g_slist_free (recent_info->groups);
1378
1379       recent_info->groups = NULL;
1380     }
1381
1382   if (recent_info->icon)
1383     g_object_unref (recent_info->icon);
1384
1385   g_free (recent_info);
1386 }
1387
1388 /**
1389  * gtk_recent_info_ref:
1390  * @info: a #GtkRecentInfo
1391  *
1392  * Increases the reference count of @recent_info by one.
1393  *
1394  * Return value: the recent info object with its reference count increased
1395  *   by one.
1396  *
1397  * Since: 2.10
1398  */
1399 GtkRecentInfo *
1400 gtk_recent_info_ref (GtkRecentInfo *info)
1401 {
1402   g_return_val_if_fail (info != NULL, NULL);
1403   g_return_val_if_fail (info->ref_count > 0, NULL);
1404
1405   info->ref_count += 1;
1406
1407   return info;
1408 }
1409
1410 /**
1411  * gtk_recent_info_unref:
1412  * @info: a #GtkRecentInfo
1413  *
1414  * Decreases the reference count of @info by one.  If the reference
1415  * count reaches zero, @info is deallocated, and the memory freed.
1416  *
1417  * Since: 2.10
1418  */
1419 void
1420 gtk_recent_info_unref (GtkRecentInfo *info)
1421 {
1422   g_return_if_fail (info != NULL);
1423   g_return_if_fail (info->ref_count > 0);
1424
1425   info->ref_count -= 1;
1426
1427   if (info->ref_count == 0)
1428     gtk_recent_info_free (info);
1429 }
1430
1431 /**
1432  * gtk_recent_info_get_uri:
1433  * @info: a #GtkRecentInfo
1434  *
1435  * Gets the URI of the resource.
1436  *
1437  * Return value: the URI of the resource.  The returned string is
1438  *   owned by the recent manager, and should not be freed.
1439  *
1440  * Since: 2.10
1441  */
1442 G_CONST_RETURN gchar *
1443 gtk_recent_info_get_uri (GtkRecentInfo *info)
1444 {
1445   g_return_val_if_fail (info != NULL, NULL);
1446
1447   return info->uri;
1448 }
1449
1450 /**
1451  * gtk_recent_info_get_display_name:
1452  * @info: a #GtkRecentInfo
1453  *
1454  * Gets the name of the resource.  If none has been defined, the basename
1455  * of the resource is obtained.
1456  *
1457  * Return value: the display name of the resource.  The returned string
1458  *   is owned by the recent manager, and should not be freed.
1459  *
1460  * Since: 2.10
1461  */
1462 G_CONST_RETURN gchar *
1463 gtk_recent_info_get_display_name (GtkRecentInfo *info)
1464 {
1465   g_return_val_if_fail (info != NULL, NULL);
1466
1467   if (!info->display_name)
1468     info->display_name = gtk_recent_info_get_short_name (info);
1469
1470   return info->display_name;
1471 }
1472
1473 /**
1474  * gtk_recent_info_get_description:
1475  * @info: a #GtkRecentInfo
1476  *
1477  * Gets the (short) description of the resource.
1478  *
1479  * Return value: the description of the resource.  The returned string
1480  *   is owned by the recent manager, and should not be freed.
1481  *
1482  * Since: 2.10
1483  **/
1484 G_CONST_RETURN gchar *
1485 gtk_recent_info_get_description (GtkRecentInfo *info)
1486 {
1487   g_return_val_if_fail (info != NULL, NULL);
1488
1489   return info->description;
1490 }
1491
1492 /**
1493  * gtk_recent_info_get_mime_type:
1494  * @info: a #GtkRecentInfo
1495  *
1496  * Gets the MIME type of the resource.
1497  *
1498  * Return value: the MIME type of the resource.  The returned string
1499  *   is owned by the recent manager, and should not be freed.
1500  *
1501  * Since: 2.10
1502  */
1503 G_CONST_RETURN gchar *
1504 gtk_recent_info_get_mime_type (GtkRecentInfo *info)
1505 {
1506   g_return_val_if_fail (info != NULL, NULL);
1507
1508   if (!info->mime_type)
1509     info->mime_type = g_strdup (GTK_RECENT_DEFAULT_MIME);
1510
1511   return info->mime_type;
1512 }
1513
1514 /**
1515  * gtk_recent_info_get_added:
1516  * @info: a #GtkRecentInfo
1517  *
1518  * Gets the timestamp (seconds from system's Epoch) when the resource
1519  * was added to the recently used resources list.
1520  *
1521  * Return value: the number of seconds elapsed from system's Epoch when
1522  *   the resource was added to the list, or -1 on failure.
1523  *
1524  * Since: 2.10
1525  */
1526 time_t
1527 gtk_recent_info_get_added (GtkRecentInfo *info)
1528 {
1529   g_return_val_if_fail (info != NULL, (time_t) -1);
1530
1531   return info->added;
1532 }
1533
1534 /**
1535  * gtk_recent_info_get_modified:
1536  * @info: a #GtkRecentInfo
1537  *
1538  * Gets the timestamp (seconds from system's Epoch) when the resource
1539  * was last modified.
1540  *
1541  * Return value: the number of seconds elapsed from system's Epoch when
1542  *   the resource was last modified, or -1 on failure.
1543  *
1544  * Since: 2.10
1545  */
1546 time_t
1547 gtk_recent_info_get_modified (GtkRecentInfo *info)
1548 {
1549   g_return_val_if_fail (info != NULL, (time_t) -1);
1550
1551   return info->modified;
1552 }
1553
1554 /**
1555  * gtk_recent_info_get_visited:
1556  * @info: a #GtkRecentInfo
1557  *
1558  * Gets the timestamp (seconds from system's Epoch) when the resource
1559  * was last visited.
1560  *
1561  * Return value: the number of seconds elapsed from system's Epoch when
1562  *   the resource was last visited, or -1 on failure.
1563  *
1564  * Since: 2.10
1565  */
1566 time_t
1567 gtk_recent_info_get_visited (GtkRecentInfo *info)
1568 {
1569   g_return_val_if_fail (info != NULL, (time_t) -1);
1570
1571   return info->visited;
1572 }
1573
1574 /**
1575  * gtk_recent_info_get_private_hint:
1576  * @info: a #GtkRecentInfo
1577  *
1578  * Gets the value of the "private" flag.  Resources in the recently used
1579  * list that have this flag set to %TRUE should only be displayed by the
1580  * applications that have registered them.
1581  *
1582  * Return value: %TRUE if the private flag was found, %FALSE otherwise.
1583  *
1584  * Since: 2.10
1585  */
1586 gboolean
1587 gtk_recent_info_get_private_hint (GtkRecentInfo *info)
1588 {
1589   g_return_val_if_fail (info != NULL, FALSE);
1590
1591   return info->is_private;
1592 }
1593
1594
1595 static RecentAppInfo *
1596 recent_app_info_new (const gchar *app_name)
1597 {
1598   RecentAppInfo *app_info;
1599
1600   g_assert (app_name != NULL);
1601
1602   app_info = g_new0 (RecentAppInfo, 1);
1603   app_info->name = g_strdup (app_name);
1604   app_info->exec = NULL;
1605   app_info->count = 1;
1606   app_info->stamp = time (NULL);
1607
1608   return app_info;
1609 }
1610
1611 static void
1612 recent_app_info_free (RecentAppInfo *app_info)
1613 {
1614   if (!app_info)
1615     return;
1616
1617   g_free (app_info->name);
1618
1619   g_free (app_info->exec);
1620
1621   g_free (app_info);
1622 }
1623
1624 /**
1625  * gtk_recent_info_get_application_info:
1626  * @info: a #GtkRecentInfo
1627  * @app_name: the name of the application that has registered this item
1628  * @app_exec: return location for the string containing the command line
1629  * @count: return location for the number of times this item was registered
1630  * @time_: return location for the timestamp this item was last registered
1631  *    for this application
1632  *
1633  * Gets the data regarding the application that has registered the resource
1634  * pointed by @info.
1635  *
1636  * If the command line contains any escape characters defined inside the
1637  * storage specification, they will be expanded.
1638  *
1639  * Return value: %TRUE if an application with @app_name has registered this
1640  *   resource inside the recently used list, or %FALSE otherwise.  You should
1641  *   free the returned command line using g_free().
1642  *
1643  * Since: 2.10
1644  */
1645 gboolean
1646 gtk_recent_info_get_application_info (GtkRecentInfo  *info,
1647                                       const gchar    *app_name,
1648                                       gchar         **app_exec,
1649                                       guint          *count,
1650                                       time_t         *time_)
1651 {
1652   RecentAppInfo *ai;
1653
1654   g_return_val_if_fail (info != NULL, FALSE);
1655   g_return_val_if_fail (app_name != NULL, FALSE);
1656
1657   ai = (RecentAppInfo *) g_hash_table_lookup (info->apps_lookup,
1658                                               app_name);
1659   if (!ai)
1660     {
1661       g_warning ("No registered application with name '%s' "
1662                  "for item with URI '%s' found",
1663                  app_name,
1664                  info->uri);
1665       return FALSE;
1666     }
1667
1668   if (app_exec)
1669     *app_exec = ai->exec;
1670
1671   if (count)
1672     *count = ai->count;
1673
1674   if (time_)
1675     *time_ = ai->stamp;
1676
1677   return TRUE;
1678 }
1679
1680 /**
1681  * gtk_recent_info_get_applications:
1682  * @info: a #GtkRecentInfo
1683  * @length: return location for the length of the returned list, or %NULL
1684  *
1685  * Retrieves the list of applications that have registered this resource.
1686  *
1687  * Return value: a newly allocated %NULL-terminated array of strings.
1688  *   Use g_strfreev() to free it.
1689  *
1690  * Since: 2.10
1691  */
1692 gchar **
1693 gtk_recent_info_get_applications (GtkRecentInfo *info,
1694                                   gsize         *length)
1695 {
1696   GSList *l;
1697   gchar **retval;
1698   gsize n_apps, i;
1699
1700   g_return_val_if_fail (info != NULL, NULL);
1701
1702   if (!info->applications)
1703     {
1704       if (length)
1705         *length = 0;
1706
1707       return NULL;
1708     }
1709
1710   n_apps = g_slist_length (info->applications);
1711
1712   retval = g_new0 (gchar *, n_apps + 1);
1713
1714   for (l = info->applications, i = 0;
1715        l != NULL;
1716        l = l->next)
1717     {
1718       RecentAppInfo *ai = (RecentAppInfo *) l->data;
1719
1720       g_assert (ai != NULL);
1721
1722       retval[i++] = g_strdup (ai->name);
1723     }
1724   retval[i] = NULL;
1725
1726   if (length)
1727     *length = i;
1728
1729   return retval;
1730 }
1731
1732 /**
1733  * gtk_recent_info_has_application:
1734  * @info: a #GtkRecentInfo
1735  * @app_name: a string containing an application name
1736  *
1737  * Checks whether an application registered this resource using @app_name.
1738  *
1739  * Return value: %TRUE if an application with name @app_name was found,
1740  *   %FALSE otherwise.
1741  *
1742  * Since: 2.10
1743  */
1744 gboolean
1745 gtk_recent_info_has_application (GtkRecentInfo *info,
1746                                  const gchar   *app_name)
1747 {
1748   g_return_val_if_fail (info != NULL, FALSE);
1749   g_return_val_if_fail (app_name != NULL, FALSE);
1750
1751   return (NULL != g_hash_table_lookup (info->apps_lookup, app_name));
1752 }
1753
1754 /**
1755  * gtk_recent_info_last_application:
1756  * @info: a #GtkRecentInfo
1757  *
1758  * Gets the name of the last application that have registered the
1759  * recently used resource represented by @info.
1760  *
1761  * Return value: an application name.  Use g_free() to free it.
1762  *
1763  * Since: 2.10
1764  */
1765 gchar *
1766 gtk_recent_info_last_application (GtkRecentInfo  *info)
1767 {
1768   GSList *l;
1769   time_t last_stamp = (time_t) -1;
1770   gchar *name = NULL;
1771
1772   g_return_val_if_fail (info != NULL, NULL);
1773
1774   for (l = info->applications; l != NULL; l = l->next)
1775     {
1776       RecentAppInfo *ai = (RecentAppInfo *) l->data;
1777
1778       if (ai->stamp > last_stamp)
1779         {
1780           name = ai->name;
1781           last_stamp = ai->stamp;
1782         }
1783     }
1784
1785   return g_strdup (name);
1786 }
1787
1788 static GdkPixbuf *
1789 get_icon_for_mime_type (const char *mime_type,
1790                         gint        pixel_size)
1791 {
1792   GtkIconTheme *icon_theme;
1793   const char *separator;
1794   GString *icon_name;
1795   GdkPixbuf *pixbuf;
1796
1797   separator = strchr (mime_type, '/');
1798   if (!separator)
1799     return NULL;
1800
1801   icon_theme = gtk_icon_theme_get_default ();
1802
1803   /* try with the three icon name variants for MIME types */
1804
1805   /* canonicalize MIME type: foo/x-bar -> foo-x-bar */
1806   icon_name = g_string_new (NULL);
1807   g_string_append_len (icon_name, mime_type, separator - mime_type);
1808   g_string_append_c (icon_name, '-');
1809   g_string_append (icon_name, separator + 1);
1810   pixbuf = gtk_icon_theme_load_icon (icon_theme, icon_name->str,
1811                                      pixel_size,
1812                                      0,
1813                                      NULL);
1814   g_string_free (icon_name, TRUE);
1815   if (pixbuf)
1816     return pixbuf;
1817
1818   /* canonicalize MIME type, and prepend "gnome-mime-" */
1819   icon_name = g_string_new ("gnome-mime-");
1820   g_string_append_len (icon_name, mime_type, separator - mime_type);
1821   g_string_append_c (icon_name, '-');
1822   g_string_append (icon_name, separator + 1);
1823   pixbuf = gtk_icon_theme_load_icon (icon_theme, icon_name->str,
1824                                      pixel_size,
1825                                      0,
1826                                      NULL);
1827   g_string_free (icon_name, TRUE);
1828   if (pixbuf)
1829     return pixbuf;
1830
1831   /* try the MIME family icon */
1832   icon_name = g_string_new ("gnome-mime-");
1833   g_string_append_len (icon_name, mime_type, separator - mime_type);
1834   pixbuf = gtk_icon_theme_load_icon (icon_theme, icon_name->str,
1835                                      pixel_size,
1836                                      0,
1837                                      NULL);
1838   g_string_free (icon_name, TRUE);
1839
1840   return pixbuf;
1841 }
1842
1843 static GdkPixbuf *
1844 get_icon_fallback (const gchar *icon_name,
1845                    gint         size)
1846 {
1847   GtkIconTheme *icon_theme;
1848   GdkPixbuf *retval;
1849
1850   icon_theme = gtk_icon_theme_get_default ();
1851
1852   retval = gtk_icon_theme_load_icon (icon_theme, icon_name,
1853                                      size,
1854                                      GTK_ICON_LOOKUP_USE_BUILTIN,
1855                                      NULL);
1856   g_assert (retval != NULL);
1857
1858   return retval;
1859 }
1860
1861 /**
1862  * gtk_recent_info_get_icon:
1863  * @info: a #GtkRecentInfo
1864  * @size: the size of the icon in pixels
1865  *
1866  * Retrieves the icon of size @size associated to the resource MIME type.
1867  *
1868  * Return value: a #GdkPixbuf containing the icon, or %NULL. Use
1869  *   g_object_unref() when finished using the icon.
1870  *
1871  * Since: 2.10
1872  */
1873 GdkPixbuf *
1874 gtk_recent_info_get_icon (GtkRecentInfo *info,
1875                           gint           size)
1876 {
1877   GdkPixbuf *retval = NULL;
1878
1879   g_return_val_if_fail (info != NULL, NULL);
1880
1881   if (info->mime_type)
1882     retval = get_icon_for_mime_type (info->mime_type, size);
1883
1884   /* this function should never fail */
1885   if (!retval)
1886     {
1887       if (info->mime_type &&
1888           strcmp (info->mime_type, "x-directory/normal") == 0)
1889         retval = get_icon_fallback (GTK_STOCK_DIRECTORY, size);
1890       else
1891         retval = get_icon_fallback (GTK_STOCK_FILE, size);
1892     }
1893
1894   return retval;
1895 }
1896
1897 /**
1898  * gtk_recent_info_is_local:
1899  * @info: a #GtkRecentInfo
1900  *
1901  * Checks whether the resource is local or not by looking at the
1902  * scheme of its URI.
1903  *
1904  * Return value: %TRUE if the resource is local.
1905  *
1906  * Since: 2.10
1907  */
1908 gboolean
1909 gtk_recent_info_is_local (GtkRecentInfo *info)
1910 {
1911   g_return_val_if_fail (info != NULL, FALSE);
1912
1913   return has_case_prefix (info->uri, "file:/");
1914 }
1915
1916 /**
1917  * gtk_recent_info_exists:
1918  * @info: a #GtkRecentInfo
1919  *
1920  * Checks whether the resource pointed by @info still exists.  At
1921  * the moment this check is done only on resources pointing to local files.
1922  *
1923  * Return value: %TRUE if the resource exists
1924  *
1925  * Since: 2.10
1926  */
1927 gboolean
1928 gtk_recent_info_exists (GtkRecentInfo *info)
1929 {
1930   gchar *filename;
1931   struct stat stat_buf;
1932   gboolean retval = FALSE;
1933
1934   g_return_val_if_fail (info != NULL, FALSE);
1935
1936   /* we guarantee only local resources */
1937   if (!gtk_recent_info_is_local (info))
1938     return FALSE;
1939
1940   filename = g_filename_from_uri (info->uri, NULL, NULL);
1941   if (filename)
1942     {
1943       if (stat (filename, &stat_buf) == 0)
1944         retval = TRUE;
1945
1946       g_free (filename);
1947     }
1948
1949   return retval;
1950 }
1951
1952 /**
1953  * gtk_recent_info_match:
1954  * @info_a: a #GtkRecentInfo
1955  * @info_b: a #GtkRecentInfo
1956  *
1957  * Checks whether two #GtkRecentInfo structures point to the same
1958  * resource.
1959  *
1960  * Return value: %TRUE if both #GtkRecentInfo structures point to se same
1961  *   resource, %FALSE otherwise.
1962  *
1963  * Since: 2.10
1964  */
1965 gboolean
1966 gtk_recent_info_match (GtkRecentInfo *info_a,
1967                        GtkRecentInfo *info_b)
1968 {
1969   g_return_val_if_fail (info_a != NULL, FALSE);
1970   g_return_val_if_fail (info_b != NULL, FALSE);
1971
1972   return (0 == strcmp (info_a->uri, info_b->uri));
1973 }
1974
1975 /* taken from gnome-vfs-uri.c */
1976 static const gchar *
1977 get_method_string (const gchar  *substring,
1978                    gchar       **method_string)
1979 {
1980   const gchar *p;
1981   char *method;
1982
1983   for (p = substring;
1984        g_ascii_isalnum (*p) || *p == '+' || *p == '-' || *p == '.';
1985        p++)
1986     ;
1987
1988   if (*p == ':'
1989 #ifdef G_OS_WIN32
1990                 &&
1991       !(p == substring + 1 && g_ascii_isalpha (*substring))
1992 #endif
1993                                                            )
1994     {
1995       /* Found toplevel method specification.  */
1996       method = g_strndup (substring, p - substring);
1997       *method_string = g_ascii_strdown (method, -1);
1998       g_free (method);
1999       p++;
2000     }
2001   else
2002     {
2003       *method_string = g_strdup ("file");
2004       p = substring;
2005     }
2006
2007   return p;
2008 }
2009
2010 /* Stolen from gnome_vfs_make_valid_utf8() */
2011 static char *
2012 make_valid_utf8 (const char *name)
2013 {
2014   GString *string;
2015   const char *remainder, *invalid;
2016   int remaining_bytes, valid_bytes;
2017
2018   string = NULL;
2019   remainder = name;
2020   remaining_bytes = name ? strlen (name) : 0;
2021
2022   while (remaining_bytes != 0)
2023     {
2024       if (g_utf8_validate (remainder, remaining_bytes, &invalid))
2025         break;
2026
2027       valid_bytes = invalid - remainder;
2028
2029       if (string == NULL)
2030         string = g_string_sized_new (remaining_bytes);
2031
2032       g_string_append_len (string, remainder, valid_bytes);
2033       g_string_append_c (string, '?');
2034
2035       remaining_bytes -= valid_bytes + 1;
2036       remainder = invalid + 1;
2037     }
2038
2039   if (string == NULL)
2040     return g_strdup (name);
2041
2042   g_string_append (string, remainder);
2043   g_assert (g_utf8_validate (string->str, -1, NULL));
2044
2045   return g_string_free (string, FALSE);
2046 }
2047
2048 static gchar *
2049 get_uri_shortname_for_display (const gchar *uri)
2050 {
2051   gchar *name = NULL;
2052   gboolean validated = FALSE;
2053
2054   if (has_case_prefix (uri, "file:/"))
2055     {
2056       gchar *local_file;
2057
2058       local_file = g_filename_from_uri (uri, NULL, NULL);
2059
2060       if (local_file)
2061         {
2062           name = g_filename_display_basename (local_file);
2063           validated = TRUE;
2064         }
2065
2066       g_free (local_file);
2067     }
2068
2069   if (!name)
2070     {
2071       gchar *method;
2072       gchar *local_file;
2073       const gchar *rest;
2074
2075       rest = get_method_string (uri, &method);
2076       local_file = g_filename_display_basename (rest);
2077
2078       name = g_strconcat (method, ": ", local_file, NULL);
2079
2080       g_free (local_file);
2081       g_free (method);
2082     }
2083
2084   g_assert (name != NULL);
2085
2086   if (!validated && !g_utf8_validate (name, -1, NULL))
2087     {
2088       gchar *utf8_name;
2089
2090       utf8_name = make_valid_utf8 (name);
2091       g_free (name);
2092
2093       name = utf8_name;
2094     }
2095
2096   return name;
2097 }
2098
2099 /**
2100  * gtk_recent_info_get_short_name:
2101  * @info: an #GtkRecentInfo
2102  *
2103  * Computes a valid UTF-8 string that can be used as the name of the item in a
2104  * menu or list.  For example, calling this function on an item that refers to
2105  * "file:///foo/bar.txt" will yield "bar.txt".
2106  *
2107  * Return value: A newly-allocated string in UTF-8 encoding; free it with
2108  *   g_free().
2109  *
2110  * Since: 2.10
2111  */
2112 gchar *
2113 gtk_recent_info_get_short_name (GtkRecentInfo *info)
2114 {
2115   gchar *short_name;
2116
2117   g_return_val_if_fail (info != NULL, NULL);
2118
2119   if (info->uri == NULL)
2120     return NULL;
2121
2122   short_name = get_uri_shortname_for_display (info->uri);
2123
2124   return short_name;
2125 }
2126
2127 /**
2128  * gtk_recent_info_get_uri_display:
2129  * @info: a #GtkRecentInfo
2130  *
2131  * Gets a displayable version of the resource's URI.  If the resource
2132  * is local, it returns a local path; if the resource is not local,
2133  * it returns the UTF-8 encoded content of gtk_recent_info_get_uri().
2134  *
2135  * Return value: a newly allocated UTF-8 string containing the
2136  *   resource's URI or %NULL. Use g_free() when done using it.
2137  *
2138  * Since: 2.10
2139  */
2140 gchar *
2141 gtk_recent_info_get_uri_display (GtkRecentInfo *info)
2142 {
2143   gchar *retval;
2144
2145   g_return_val_if_fail (info != NULL, NULL);
2146
2147   retval = NULL;
2148   if (gtk_recent_info_is_local (info))
2149     {
2150       gchar *filename;
2151
2152       filename = g_filename_from_uri (info->uri, NULL, NULL);
2153       if (!filename)
2154         return NULL;
2155
2156       retval = g_filename_to_utf8 (filename, -1, NULL, NULL, NULL);
2157       g_free (filename);
2158     }
2159   else
2160     {
2161       retval = make_valid_utf8 (info->uri);
2162     }
2163
2164   return retval;
2165 }
2166
2167 /**
2168  * gtk_recent_info_get_age:
2169  * @info: a #GtkRecentInfo
2170  *
2171  * Gets the number of days elapsed since the last update of the resource
2172  * pointed by @info.
2173  *
2174  * Return value: a positive integer containing the number of days elapsed
2175  *   since the time this resource was last modified.
2176  *
2177  * Since: 2.10
2178  */
2179 gint
2180 gtk_recent_info_get_age (GtkRecentInfo *info)
2181 {
2182   time_t now, delta;
2183   gint retval;
2184
2185   g_return_val_if_fail (info != NULL, -1);
2186
2187   now = time (NULL);
2188
2189   delta = now - info->modified;
2190
2191   retval = (gint) (delta / (60 * 60 * 24));
2192
2193   return retval;
2194 }
2195
2196 /**
2197  * gtk_recent_info_get_groups:
2198  * @info: a #GtkRecentInfo
2199  * @length: return location for the number of groups returned, or %NULL
2200  *
2201  * Returns all groups registered for the recently used item @info.  The
2202  * array of returned group names will be %NULL terminated, so length might
2203  * optionally be %NULL.
2204  *
2205  * Return value: a newly allocated %NULL terminated array of strings.  Use
2206  *   g_strfreev() to free it.
2207  *
2208  * Since: 2.10
2209  */
2210 gchar **
2211 gtk_recent_info_get_groups (GtkRecentInfo *info,
2212                             gsize         *length)
2213 {
2214   GSList *l;
2215   gchar **retval;
2216   gsize n_groups, i;
2217
2218   g_return_val_if_fail (info != NULL, NULL);
2219
2220   if (!info->groups)
2221     {
2222       if (length)
2223         *length = 0;
2224
2225       return NULL;
2226     }
2227
2228   n_groups = g_slist_length (info->groups);
2229
2230   retval = g_new0 (gchar *, n_groups + 1);
2231
2232   for (l = info->groups, i = 0;
2233        l != NULL;
2234        l = l->next)
2235     {
2236       gchar *group_name = (gchar *) l->data;
2237
2238       g_assert (group_name != NULL);
2239
2240       retval[i++] = g_strdup (group_name);
2241     }
2242   retval[i] = NULL;
2243
2244   if (length)
2245     *length = i;
2246
2247   return retval;
2248 }
2249
2250 /**
2251  * gtk_recent_info_has_group:
2252  * @info: a #GtkRecentInfo
2253  * @group_name: name of a group
2254  *
2255  * Checks whether @group_name appears inside the groups registered for the
2256  * recently used item @info.
2257  *
2258  * Return value: %TRUE if the group was found.
2259  *
2260  * Since: 2.10
2261  */
2262 gboolean
2263 gtk_recent_info_has_group (GtkRecentInfo *info,
2264                            const gchar   *group_name)
2265 {
2266   GSList *l;
2267
2268   g_return_val_if_fail (info != NULL, FALSE);
2269   g_return_val_if_fail (group_name != NULL, FALSE);
2270
2271   if (!info->groups)
2272     return FALSE;
2273
2274   for (l = info->groups; l != NULL; l = l->next)
2275     {
2276       gchar *g = (gchar *) l->data;
2277
2278       if (strcmp (g, group_name) == 0)
2279         return TRUE;
2280     }
2281
2282   return FALSE;
2283 }
2284
2285 /*
2286  * _gtk_recent_manager_sync:
2287  *
2288  * Private function for synchronising the recent manager singleton.
2289  */
2290 void
2291 _gtk_recent_manager_sync (void)
2292 {
2293   if (recent_manager_singleton)
2294     {
2295       /* force a dump of the contents of the recent manager singleton */
2296       recent_manager_singleton->priv->is_dirty = TRUE;
2297       gtk_recent_manager_real_changed (recent_manager_singleton);
2298     }
2299 }
2300
2301 #define __GTK_RECENT_MANAGER_C__
2302 #include "gtkaliasdef.c"