home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / libnet / crawler.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  7.0 KB  |  180 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18. /*** crawler.h ****************************************************/
  19. /*   description:        html crawler                              */
  20.  
  21.  
  22.  /********************************************************************
  23.  
  24.     The crawler scans html pages and the links in those pages to a specified 
  25.     depth in a breadth first manner, optionally caching them in an external cache. 
  26.     Items are crawled sequentially - an item must finish being crawled or cached 
  27.     before the next item is crawled. Multiple instances of the crawler may be running 
  28.     at the same time.
  29.  
  30.     Depth = 1 means that only the initial page, and any images and resources that 
  31.     it contains, are cached.
  32.  
  33.     Depth = n means that the crawler will crawl to n levels deep. Assuming the 
  34.     maximum cache size is sufficient, the crawler will cache images and resources 
  35.     for each page it encounters. Normally, resources are cached after all the pages 
  36.     for a given level have been processed, but some resources are considered "required", 
  37.     meaning they will be cached immediately after the page containing them has been 
  38.     processed. An example of a "required" resource is a stylesheet.
  39.  
  40.     The crawler obeys the robots.txt directives on a site, which may allow or deny access 
  41.     to specific urls or directories. The robots.txt file is by convention at the top level
  42.     of a site.
  43.  
  44.     The type of links that are crawled are determined in pagescan.c.
  45.     The parsing code is in htmparse.c
  46.     The robots.txt parser is in robotxt.c
  47.  
  48.   $Revision: 3.1 $
  49.   $Date: 1998/03/28 03:31:25 $
  50.  
  51.  *********************************************************************/
  52.  
  53. #ifndef crawler_h___
  54. #define crawler_h___
  55.  
  56. #include "ntypes.h"        /* for MWContext */
  57. #include "prtypes.h"    /* for PRBool */
  58. #include "net.h"        /* for ExtCacheDBInfo, URL_Struct */
  59.  
  60. /* Error codes */
  61. typedef PRUint16 CRAWL_Error;
  62.  
  63. #define CRAWL_CACHE_FULL        ((CRAWL_Error)0x0001)
  64. #define CRAWL_NO_MEMORY            ((CRAWL_Error)0x0002)
  65. #define CRAWL_SERVER_ERR        ((CRAWL_Error)0x0004)
  66. #define CRAWL_INTERRUPTED        ((CRAWL_Error)0x0008)
  67.  
  68. /* these error codes indicate if and how the cache has been updated and are only
  69.    set if CRAWL_MakeCrawler was called with manageCache set to true. Note that replaced
  70.    links may not have been reported as such if the server does not provide a last
  71.    modified date.
  72. */
  73. #define CRAWL_NEW_LINK            ((CRAWL_Error)0x0010)
  74. #define CRAWL_REPLACED_LINK        ((CRAWL_Error)0x0020)
  75. #define CRAWL_REMOVED_LINK        ((CRAWL_Error)0x0040)
  76.  
  77. /* Most of the APIs require a reference to CRAWL_Crawler, which is created by CRAWL_MakeCrawler. */
  78. typedef struct _CRAWL_CrawlerStruct *CRAWL_Crawler;
  79.  
  80. /*
  81.  * Typedef for a callback executed when an item has been processed.
  82.  */
  83.  typedef void
  84. (PR_CALLBACK *CRAWL_PostProcessItemFn)(CRAWL_Crawler crawler, URL_Struct *url_s, PRBool isCached, void *data);
  85.  
  86. /*
  87.  * Typedef for a callback executed when the crawler is done.
  88.  */
  89.  typedef void
  90. (PR_CALLBACK *CRAWL_ExitFn)(CRAWL_Crawler crawler, void *data);
  91.  
  92. /****************************************************************************************/
  93. /* public API                                                                            */
  94. /****************************************************************************************/
  95.  
  96. NSPR_BEGIN_EXTERN_C
  97.  
  98. /* 
  99.     Creates a crawler which may be used for one crawling request. Subsequent requests
  100.     to crawl urls should use a separate crawler instance. Returns NULL if not enough
  101.     memory is available, or the depth is less than 1.
  102.  
  103.   Parameters:
  104.     context - needed by netlib (the crawler does not check this parameter)
  105.     siteName - url of the site
  106.     stayInSite - whether to restrict crawling to the site named.
  107.     manageCache - whether to maintain a local file describing the cache contents. 
  108.         If true, the crawler uses the file to remove dangling links from the cache
  109.         the next time it is invoked with the same cache. This is not guaranteed to
  110.         work correctly if another crawling instance uses the same cache simultaneously.
  111.     cache - the external cache. This may be NULL if the crawled items do not need
  112.         to be put in an external cache.
  113.     postProcessItemFn - a function which is called after each item has been handled
  114.         by netlib. This may be NULL.
  115.     postProcessItemData - this data is supplied as a parameter to the postProcessItemFn
  116.         and is opaque to the crawler. This may be NULL.
  117.     exitFn - a function which is called when the crawler is done or has terminated
  118.         prematurely (because the cache is full, or no memory is available). This may be NULL.
  119.     exitData - this data is supplied as a parameter to the exitFn and is opaque to
  120.         the crawler. This may be NULL.
  121. */
  122. PR_EXTERN(CRAWL_Crawler) 
  123. CRAWL_MakeCrawler(MWContext *context, 
  124.                                          char *siteName, 
  125.                                          uint8 depth, 
  126.                                          PRBool stayInSite,
  127.                                          PRBool manageCache,
  128.                                          ExtCacheDBInfo *cache,
  129.                                          CRAWL_PostProcessItemFn postProcessItemFn,
  130.                                          void *postProcessItemData,
  131.                                          CRAWL_ExitFn exitFn,
  132.                                          void *exitData);
  133.  
  134. /* 
  135.     Destroys the crawler and all memory associated with it. The crawler instance should not be
  136.     used after calling this function.
  137. */
  138. PR_EXTERN(void) 
  139. CRAWL_DestroyCrawler(CRAWL_Crawler crawler);
  140.  
  141. /* 
  142.     Starts crawling from the url. If its content type is text/html, links may be traversed. This function
  143.     returns as soon as the first network request is issued. 
  144. */
  145. PR_EXTERN(void) 
  146. CRAWL_StartCrawler(CRAWL_Crawler crawler, char *url);
  147.  
  148. /* 
  149.     Stops crawling at the next link. This function returns immediately and cannot fail. 
  150. */
  151. PR_EXTERN(void) 
  152. CRAWL_StopCrawler(CRAWL_Crawler crawler);
  153.  
  154. /* 
  155.     Returns the crawler error code. This function returns immediately and cannot fail. 
  156. */
  157. PR_EXTERN(CRAWL_Error) 
  158. CRAWL_GetError(CRAWL_Crawler crawler);
  159.  
  160. /* 
  161.     Returns true if the crawler has stopped, which is the case before and after crawling. Returns
  162.     immediately and cannot fail.
  163. */
  164. PR_EXTERN(PRBool) 
  165. CRAWL_IsStopped(CRAWL_Crawler crawler);
  166.  
  167. NSPR_END_EXTERN_C
  168.  
  169. /* 
  170.     Stream function for crawling resources. Resources are not parsed, but the crawler checks the
  171.     content length to see if the cache would be exceeded.
  172. */
  173. PUBLIC NET_StreamClass*
  174. CRAWL_CrawlerResourceConverter(int format_out,
  175.                                 void *data_object,
  176.                                 URL_Struct *URL_s,
  177.                                 MWContext  *window_id);
  178.  
  179. #endif /* crawler_h___ */
  180.