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