home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _adc0db5cdc48b48f8a9d1916a157c648 < prev    next >
Text File  |  2000-03-23  |  12KB  |  298 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Netscape::History - object class for accessing Netscape history database</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Netscape::History - object class for accessing Netscape history database</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#please note">PLEASE NOTE</A></LI>
  28.         <LI><A HREF="#constructor">CONSTRUCTOR</A></LI>
  29.     </UL>
  30.  
  31.     <LI><A HREF="#methods">METHODS</A></LI>
  32.     <UL>
  33.  
  34.         <LI><A HREF="#get_url  get a specific url from your history">get_url - get a specific URL from your history</A></LI>
  35.         <LI><A HREF="#next_url  get the next url from your history database">next_url - get the next URL from your history database</A></LI>
  36.         <LI><A HREF="#delete_url  remove a url from the history database">delete_url - remove a URL from the history database</A></LI>
  37.         <LI><A HREF="#add_url  add a url to the history database">add_url - add a URL to the history database</A></LI>
  38.         <LI><A HREF="#rewind  reset internal url pointer to first url in history">rewind - reset internal URL pointer to first URL in history</A></LI>
  39.         <LI><A HREF="#close  close the history database">close - close the history database</A></LI>
  40.     </UL>
  41.  
  42.     <LI><A HREF="#examples">EXAMPLES</A></LI>
  43.     <UL>
  44.  
  45.         <LI><A HREF="#display contents of history">DISPLAY CONTENTS OF HISTORY</A></LI>
  46.         <LI><A HREF="#merge two history files">MERGE TWO HISTORY FILES</A></LI>
  47.     </UL>
  48.  
  49.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  50.     <LI><A HREF="#author">AUTHOR</A></LI>
  51.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  52. </UL>
  53. <!-- INDEX END -->
  54.  
  55. <HR>
  56. <P>
  57. <H1><A NAME="name">NAME</A></H1>
  58. <P>Netscape::History - object class for accessing Netscape history database</P>
  59. <P>
  60. <HR>
  61. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  62. <UL>
  63. <LI>Windows</LI>
  64. </UL>
  65. <HR>
  66. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  67. <PRE>
  68.     use Netscape::History;
  69. </PRE>
  70. <PRE>
  71.  
  72.     $history = new Netscape::History();
  73.     while (defined($url = $history->next_url() ))
  74.     {
  75.     }</PRE>
  76. <P>
  77. <HR>
  78. <H1><A NAME="description">DESCRIPTION</A></H1>
  79. <P>The <CODE>Netscape::History</CODE> module implements an object class for
  80. accessing the history database maintained by the Netscape web browser.
  81. The history database keeps a list of all URLs you have visited,
  82. and is used by Netscape to change the color of URLs which you have
  83. previously visited, for example.</P>
  84. <P>With this module, you can get at the URLs stored in a Netscape history
  85. file, delete URLs, and add new ones. With the associated
  86. <A HREF="#item_Netscape%3A%3AHistoryURL"><CODE>Netscape::HistoryURL</CODE></A> module you can access the information which
  87. is associated with each URL.</P>
  88. <P><STRONG>Please Note:</STRONG> the database format for the browser history was changed
  89. with Netscape 4. Previously only the time of most recent visit was
  90. available; now you can also get at the time of your first visit,
  91. the number of visits, the title of the referenced page, and another value.</P>
  92. <P>
  93. <H2><A NAME="please note">PLEASE NOTE</A></H2>
  94. <P>In version 2.00 of this module, you had to set the
  95. <CODE>$Netscape::History::NETSCAPE_VERSION</CODE> variable
  96. to the major version number of the Netscape you were using,
  97. since there was a change in the information stored for each URL
  98. between versions 3 and 4.
  99. In a subsequent version we removed the need for the variable,
  100. thanks to a suggestion from Jimmy Aitken.</P>
  101. <P>Previously, setting the variable would silently do nothing,
  102. from this version onwards it will result in an error.</P>
  103. <P>
  104. <H2><A NAME="constructor">CONSTRUCTOR</A></H2>
  105. <PRE>
  106.     $history = new Netscape::History();</PRE>
  107. <P>This creates a new instance of the Netscape::History object class.
  108. You can optionally pass the path to the history database as an
  109. argument to the constructor, as in:</P>
  110. <PRE>
  111.     $history = new Netscape::History('/home/bob/.netscape/history.db');</PRE>
  112. <P>If you do not specify the file, then the constructor will use:</P>
  113. <PRE>
  114.     $HOME/.netscape/history.db</PRE>
  115. <P>If the Netscape history database does not exist, a warning message
  116. will be generated, and the constructor will return <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A>.</P>
  117. <P>
  118. <HR>
  119. <H1><A NAME="methods">METHODS</A></H1>
  120. <P>The <STRONG>Netscape::History</STRONG> class implements the following methods:</P>
  121. <UL>
  122. <LI>
  123. get_url - get a specific URL from your history
  124. <P></P>
  125. <LI>
  126. rewind - reset history database to first URL
  127. <P></P>
  128. <LI>
  129. next_url - get next URL from your history
  130. <P></P>
  131. <LI>
  132. delete_url - remove a URL from your history
  133. <P></P>
  134. <LI>
  135. add_url - add a URL to the history file
  136. <P></P>
  137. <LI>
  138. close - close the history database
  139. <P></P></UL>
  140. <P>Each of the methods is described separately below.</P>
  141. <P>
  142. <H2><A NAME="get_url  get a specific url from your history">get_url - get a specific URL from your history</A></H2>
  143. <PRE>
  144.     $url = $history->get_url( URL );</PRE>
  145. <P>This method is used to extract information about a specific URL
  146. from your history database.</P>
  147. <P>This method takes a URL (which could be just a text string,
  148. or an object of class URI::URL) and returns an instance
  149. of Netscape::HistoryURL.</P>
  150. <P>
  151. <H2><A NAME="next_url  get the next url from your history database">next_url - get the next URL from your history database</A></H2>
  152. <PRE>
  153.     $url = $history->next_url();</PRE>
  154. <P>This method returns the next URL from your history database.
  155. If you want to process all URLs in the database, you
  156. should call the <STRONG>rewind</STRONG> method before looping over all URLs.</P>
  157. <P>The URL returned is an instance of the Netscape::HistoryURL class,
  158. which works just like an instance of URI::URL, but provides an
  159. extra methods, as described in the documentation for Netscape::HistoryURL.</P>
  160. <P>
  161. <H2><A NAME="delete_url  remove a url from the history database">delete_url - remove a URL from the history database</A></H2>
  162. <PRE>
  163.     $history->delete_url($url);</PRE>
  164. <P>This method is used to remove a URL from your history database.
  165. The URL passed can be a simple text string with the URL,
  166. or an instance of Netscape::HistoryURL, URI::URL, or any other
  167. class which can be rendered into a string.</P>
  168. <P>
  169. <H2><A NAME="add_url  add a url to the history database">add_url - add a URL to the history database</A></H2>
  170. <PRE>
  171.     $history->add_url( URL );</PRE>
  172. <P>This method is used to add a URL to a history database.
  173. This might be useful if you are merging information from multiple
  174. history databases, for example.</P>
  175. <P>If the URL passed is an instance of Netscape::HistoryURL,
  176. then the information available will be stored.</P>
  177. <P>If the URL is specified as a text string, is derived from URI::URL,
  178. then a Netscape::HistoryURL will be created with the following:</P>
  179. <PRE>
  180.     LAST   = current time
  181.     FIRST  = current time
  182.     COUNT  = 1
  183.     EXPIRE = 1
  184.     TITLE  = ''</PRE>
  185. <P>If the EXPIRE field is not set to 1, then it won't appear
  186. in Netscape's history window. Not really sure why :-)</P>
  187. <P>
  188. <H2><A NAME="rewind  reset internal url pointer to first url in history">rewind - reset internal URL pointer to first URL in history</A></H2>
  189. <PRE>
  190.     $history->rewind();</PRE>
  191. <P>This method is used to move the history database's internal pointer
  192. to the first URL in your history database.
  193. You don't need to bother with this if you have just created the object,
  194. but it doesn't harm anything if you do.</P>
  195. <P>
  196. <H2><A NAME="close  close the history database">close - close the history database</A></H2>
  197. <PRE>
  198.     $history->close();</PRE>
  199. <P>This closes the history database. The destructor will do this automatically
  200. for you, so most of time you don't actually have to bother calling this
  201. method explicitly. Good programming style says you should though :-)</P>
  202. <P>
  203. <HR>
  204. <H1><A NAME="examples">EXAMPLES</A></H1>
  205. <P>
  206. <H2><A NAME="display contents of history">DISPLAY CONTENTS OF HISTORY</A></H2>
  207. <P>The following example illustrates use of this module,
  208. and the <STRONG>visit_time()</STRONG> method of the URLs returned.
  209. The program will list all URLs visited, along with visit time.
  210. The Date::Format module is used to format the visit time.</P>
  211. <PRE>
  212.     #!/usr/bin/perl -w
  213. </PRE>
  214. <PRE>
  215.  
  216.     use Netscape::History;
  217.     use Date::Format;
  218.     use strict;</PRE>
  219. <PRE>
  220.  
  221.     my $history;
  222.     my $url;</PRE>
  223. <PRE>
  224.  
  225.     $history = new Netscape::History;
  226.     while (defined($url = $history->next_url() ))
  227.     {
  228.         print "$url :\n";
  229.         print "    First  : ", ctime($url->first_visit_time());
  230.         print "    Last   : ", ctime($url->last_visit_time());
  231.         print "    Count  : ", $url->visit_count(), "\n";
  232.         print "    Expire : ", $url->expire(), "\n";
  233.         print "    Title  : ", $url->title(), "\n";
  234.     }
  235.     $history->close();</PRE>
  236. <P>
  237. <H2><A NAME="merge two history files">MERGE TWO HISTORY FILES</A></H2>
  238. <P>The following example illustrates use of the <CODE>add_url</CODE> method
  239. to merge two history databases. We read all URLs from <CODE>history2.db</CODE>,
  240. and merge them into <CODE>history1.db</CODE>, overwriting any duplicates.</P>
  241. <PRE>
  242.     $history1 = new Netscape::History("history1.db");
  243.     $history2 = new Netscape::History("history2.db");
  244.     while (defined($url = $history2->next_url() ))
  245.     {
  246.         $history1->add_url($url);
  247.     }
  248.     $history1->close();
  249.     $history2->close();</PRE>
  250. <P>
  251. <HR>
  252. <H1><A NAME="see also">SEE ALSO</A></H1>
  253. <DL>
  254. <DT><STRONG><A NAME="item_Netscape%3A%3AHistoryURL"><A HREF="../../../site/lib/Netscape/HistoryURL.html">the Netscape::HistoryURL manpage</A></A></STRONG><BR>
  255. <DD>
  256. When you call the <EM>next_url</EM> method, you are returned instances of this class.
  257. <P></P>
  258. <DT><STRONG><A NAME="item_DB_File"><A HREF="../../../lib/DB_File.html">the DB_File manpage</A></A></STRONG><BR>
  259. <DD>
  260. The Netscape history file is just a Berkeley DB File,
  261. which we access using the <A HREF="#item_DB_File"><CODE>DB_File</CODE></A> module. You can
  262. use a different DB_File compatible library (such as
  263. <CODE>DB_File::SV185</CODE>) by running
  264. <PRE>
  265.   use Netscape::History dblib => 'DB_File::SV185'</PRE>
  266. <P>in which case you are only depending on the specified
  267. library and not <A HREF="#item_DB_File"><CODE>DB_File</CODE></A>.</P>
  268. <P></P>
  269. <DT><STRONG><A NAME="item_URI%3A%3AURL"><A HREF="../../../site/lib/URI/URL.html">the URI::URL manpage</A></A></STRONG><BR>
  270. <DD>
  271. The underlying class for <A HREF="../../../site/lib/Netscape/HistoryURL.html">the Netscape::HistoryURL manpage</A>,
  272. which provides the mechanisms for manipulating URLs.
  273. <P></P>
  274. <DT><STRONG><A NAME="item_Date%3A%3AFormat"><A HREF="../../../site/lib/Date/Format.html">the Date::Format manpage</A></A></STRONG><BR>
  275. <DD>
  276. Functions for formatting time and date in strings.
  277. <P></P></DL>
  278. <P>
  279. <HR>
  280. <H1><A NAME="author">AUTHOR</A></H1>
  281. <P>Neil Bowers <<A HREF="mailto:neilb@cre.canon.co.uk">neilb@cre.canon.co.uk</A>>, and
  282. Richard Taylor <<A HREF="mailto:rit@cre.canon.co.uk">rit@cre.canon.co.uk</A>>.</P>
  283. <P>
  284. <HR>
  285. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  286. <P>Copyright (c) 1997-1999 Canon Research Centre Europe. All rights reserved.
  287. This module is free software; you can redistribute it and/or modify
  288. it under the same terms as Perl itself.</P>
  289. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  290. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  291. <STRONG><P CLASS=block> Netscape::History - object class for accessing Netscape history database</P></STRONG>
  292. </TD></TR>
  293. </TABLE>
  294.  
  295. </BODY>
  296.  
  297. </HTML>
  298.