internals

harvest是一个下载html网页得机器人

                                    Updated for curl 7.9.1 on November 2, 2001
                                  _   _ ____  _     
                              ___| | | |  _ \| |    
                             / __| | | | |_) | |    
                            | (__| |_| |  _ <| |___ 
                             \___|\___/|_| \_\_____|

INTERNALS

 The project is split in two. The library and the client. The client part uses
 the library, but the library is designed to allow other applications to use
 it.

 The largest amount of code and complexity is in the library part.

CVS
===
 All changes to the sources are committed to the CVS repository as soon as
 they're somewhat verified to work. Changes shall be commited as independently
 as possible so that individual changes can be easier spotted and tracked
 afterwards.

 Tagging shall be used extensively, and by the time we release new archives we
 should tag the sources with a name similar to the released version number.

Windows vs Unix
===============

 There are a few differences in how to program curl the unix way compared to
 the Windows way. The four perhaps most notable details are:

 1. Different function names for socket operations.

   In curl, this is solved with defines and macros, so that the source looks
   the same at all places except for the header file that defines them. The
   macros in use are sclose(), sread() and swrite().

 2. Windows requires a couple of init calls for the socket stuff.

   Those must be made by the application that uses libcurl, in curl that means
   src/main.c has some code #ifdef'ed to do just that.

 3. The file descriptors for network communication and file operations are
    not easily interchangable as in unix.

   We avoid this by not trying any funny tricks on file descriptors.

 4. When writing data to stdout, Windows makes end-of-lines the DOS way, thus
    destroying binary data, although you do want that conversion if it is
    text coming through... (sigh)

   We set stdout to binary under windows

 Inside the source code, We make an effort to avoid '#ifdef [Your OS]'. All
 conditionals that deal with features *should* instead be in the format
 '#ifdef HAVE_THAT_WEIRD_FUNCTION'. Since Windows can't run configure scripts,
 we maintain two config-win32.h files (one in lib/ and one in src/) that are
 supposed to look exactly as a config.h file would have looked like on a
 Windows machine!

 Generally speaking: always remember that this will be compiled on dozens of
 operating systems. Don't walk on the edge.

Library
=======

 There are plenty of entry points to the library, namely each publicly defined
 function that libcurl offers to applications. All of those functions are
 rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are
 put in the lib/easy.c file.

 curl_global_init_() and curl_global_cleanup() should be called by the
 application to initialize and clean up global stuff in the library. As of
 today, it can handle the global SSL initing if SSL is enabled and it can init
 the socket layer on windows machines. libcurl itself has no "global" scope.

 All printf()-style functions use the supplied clones in lib/mprintf.c. This
 makes sure we stay absolutely platform independent.

 curl_easy_init() allocates an internal struct and makes some initializations.
 The returned handle does not reveal internals. This is the 'SessionHandle'
 struct which works as an "anchor" struct for all curl_easy functions. All
 connections performed will get connect-specific data allocated that should be
 used for things related to particular connections/requests.

 curl_easy_setopt() takes three arguments, where the option stuff must be
 passed in pairs: the parameter-ID and the parameter-value. The list of
 options is documented in the man page. This function mainly sets things in
 the 'SessionHandle' struct.

 curl_easy_perform() does a whole lot of things:

 It starts off in the lib/easy.c file by calling Curl_perform() and the main
 work then continues in lib/url.c. The flow continues with a call to
 Curl_connect() to connect to the remote site.

 o Curl_connect()

   ... analyzes the URL, it separates the different components and connects to
   the remote host. This may involve using a proxy and/or using SSL. The
   Curl_gethost() function in lib/hostip.c is used for looking up host names.

   When Curl_connect is done, we are connected to the remote site. Then it is
   time to tell the server to get a document/file. Curl_do() arranges this.

   This function makes sure there's an allocated and initiated 'connectdata'
   struct that is used for this particular connection only (although there may
   be several requests performed on the same connect). A bunch of things are
   inited/inherited from the SessionHandle struct.

 o Curl_do()

   Curl_do() makes sure the proper protocol-specific function is called. The
   functions are named after the protocols they handle. Curl_ftp(),
   Curl_http(), Curl_dict(), etc. They all reside in their respective files
   (ftp.c, http.c and dict.c). HTTPS is handled by Curl_http() and FTPS by
   Curl_ftp().

   The protocol-specific functions of course deal with protocol-specific
   negotiations and setup. They have access to the Curl_sendf() (from
   lib/sendf.c) function to send printf-style formatted data to the remote
   host and when they're ready to make the actual file transfer they call the
   Curl_Transfer() function (in lib/transfer.c) to setup the transfer and
   returns.

   Starting in 7.9.1, if this DO function fails and the connection is being
   re-used, libcurl will then close this connection, setup a new connection
   and re-issue the DO request on that. This is because there is no way to be
   perfectly sure that we have discovered a dead connection before the DO
   function and thus we might wrongly be re-using a connection that was closed
   by the remote peer.

 o Transfer()

   Curl_perform() then calls Transfer() in lib/transfer.c that performs
   the entire file transfer.

   During transfer, the progress functions in lib/progress.c are called at a
   frequent interval (or at the user's choice, a specified callback might get
   called). The speedcheck functions in lib/speedcheck.c are also used to
   verify that the transfer is as fast as required.

 o Curl_done()

   Called after a transfer is done. This function takes care of everything
   that has to be done after a transfer. This function attempts to leave
   matters in a state so that Curl_do() should be possible to call again on
   the same connection (in a persistent connection case). It might also soon
   be closed with Curl_disconnect().

 o Curl_disconnect()

   When doing normal connections and transfers, no one ever tries to close any
   connections so this is not normally called when curl_easy_perform() is
   used. This function is only used when we are certain that no more transfers
   is going to be made on the connection. It can be also closed by force, or
   it can be called to make sure that libcurl doesn't keep too many
   connections alive at the same time (there's a default amount of 5 but that
   can be changed with the CURLOPT_MAXCONNECTS option).

   This function cleans up all resources that are associated with a single
   connection.

 Curl_perform() is the function that does the main "connect - do - transfer -
 done" loop. It loops if there's a Location: to follow.

 When completed, the curl_easy_cleanup() should be called to free up used
 resources. It runs Curl_disconnect() on all open connectons.

 A quick roundup on internal function sequences (many of these call
 protocol-specific function-pointers):

  curl_connect - connects to a remote site and does initial connect fluff
   This also checks for an existing connection to the requested site and uses
   that one if it is possible.

   curl_do - starts a transfer
    curl_transfer() - transfers data
   curl_done - ends a transfer

  curl_disconnect - disconnects from a remote site. This is called when the
   disconnect is really requested, which doesn't necessarily have to be
   exactly after curl_done in case we want to keep the connection open for
   a while.

 HTTP(S)

 HTTP offers a lot and is the protocol in curl that uses the most lines of
 code. There is a special file (lib/formdata.c) that offers all the multipart
 post functions.