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