RbFetch Routines


The RbFetch routines are used to schedule and fetch all the necessary pages for your book. To use them, you must have already called the RbFetch_init() function from your application (and also have called the RbMake_init() function too). You pass in a function pointer to the init call that specifies the RbFetchStatusFunc -- this is used to provide your program with feedback of what's happening so it can keep the user informed.

When your application is all done with its .rb-creation work, you should call the RbFetch_cleanup() function. (You'll also want to call the RbMake_cleanup() call at the same time.)

The RbFetch routines do not have their own associated object, but instead, most of them take an RbMake object pointer to indicate where the created RbPage objects will go.

A typical application will simply call the RbFetch_getURL() function for each URL that you want to include in the book, and then call the RbFetch_loop() function (which will return when all the files have been fetched and added to the RbMake object).

If you want to include the contents of an existing .rb file in your new .rb file, you need to first call RbFetch_prepareForRbContents(), followed by RbFetch_getRbContents(). If you've chosen to call RbMake_addPageName() on all your URLs prior to calling RbMake_create(), you should call RbFetch_prepareForRbContents() on all the necessary .rb files during that phase. If you are not doing this, simply call the two functions in sequence.

Fetch-Status Callback

The RbFetchStatusFunc (which is a function pointer supplied to RbFetch_init()) is called every time a file has been either successfully fetched or has failed (and is called immediately after the call to RbPage_write() but prior to calling RbPage_drop() on an erroneous page). The status routine gets passed several things: a pointer to the RbMake object, a string that represents the page's ToC pagename (if page-joining is going on, this is the name the page would have had if it were not becoming a part of a larger group joined), the full URL is provided, an error pointer (which is NULL if no error happened), and a numeric "joinCnt" value (which is negative when reporting the status of an HTML page that is being joined into a collective page, 0 if the page is being stored normally, and a positive count "N" if we're now writing out the "N" pages that we joined together.

A couple useful status functions from the RbMake class are especially useful if you use them in your RbFetchStatusFunc routine: RbMake_getDoneCount(), and RbMake_getPageCount(). These can be used to tell the user how many page have already been fetched, and how many are still outstanding.