3.2 Manage

When you have already initialed rur, you may get a RurItem list which should contain useful information for your application. For example, you may use the uri member of the list's item to let user select and open them again and jump to the page number last time visited. This subsection is concentrate on the management of the RurItem list. You can do the following operate on the RurItem list currently:

1. Add new item

       int rur_opened_file(const char *opend_name, RurItem **list);
   

   Once user opened a [new] file in your application, you can tell rur to manage the opened file's record use the function rur_opened_file(). The opened_name parameter will be stored as the uri member of the new item, the list parameter is the pointer point to the list pointer which is returned on subsection 3.1. The return value of this function described as following:
   • $-$1
     opened_name is a fresh uri in *list, but add failure because of system failure. Or, parameter you input not legal.
   • 0
     opened_name is a fresh uri in *list, and add to the *list as a new item in success. The app_name and mime_type is same as the other items in the *list, the timestamp is the time added the item, the count member is 1, and the status of the item is NEW(this is not so important for the user, it is used internal by rur). The value of list shall be changed in this case with the new item as it's first item(except the list is a One-Item RurItem list with the item's uri is NULL which has described in subsection 3.1, rur will reuse this item to store the new item), this is why the list parameter must be a pointer to a pointer.

     (By the way, The default page number is 1 of a new item. If your application is treated with some file like html that does not have page number. You can ignore this attribute of RurItem list.)

   • 1
     In the *list, there is already a item with it's uri equal to opened_name you offered. So, no item will be add to the *list, but rur will update the original item's timestamp to current time, add count by 1, and change status member to UPDATE in this case.

2. Remove old item

       int rur_delete_file(RurItem *list, const char *uri);
   

   Once user closed a file or activated the remove one file's history record function you offered, you can call this function to tell rur do not manage the item no longer which the uri is equal to you offered. This function's return value also worth to be check:
   • $-$1
     Parameter you offered to rur not legal.
   • 0
     Item in list with the uri same as you offered has been deleted successful. Please note that the item hasn't been deleted actually, rur just set item's status value to DELETE for further use. So, I advise you check the item's status when you re-offer the uri list for user select to not offer the DELETE-ed item to user.
   • 1
     Item delete failure, this is mostly because of the uri you offered is not exist in the RurItem list.
   Currently, to remove more than one file's records from file ~/.recently-used.xbel(for example: you want to remove all the history record you have made), you must call this function one-by-one. If necessary, you can improve this function to do such things more wiseness.

3. Change one item's page number

       int rur_save_pagenum(RurItem *list, const char *uri, int pagenum);
   

   If you call this function, it mostly like that your user have select another file to use. So, you want to save the file's page number your user used just now. Or, user want to quit from your application, you need to save current file's page number for next time you visit it.

   The pagenum parameter interpreted by rur as following:

   • $<$0
     Save the item's page_num to 1 whose uri equal to the parameter.
   • =0
     Make the item's page_num++ whose uri member equal to the parameter.
   • $>$0
     Save the item's page_num to pagenum actually as the parameter you specified.
   This function's return value is as the same as remove item function, 0 represent save page number successful.