GrabUrl Functions

Overview

These functions are used to grab web pages via http. The rbmake library may call these routines internally if libwww was not compiled into the library.

You must call GrabUrl_init() with a GrabUrlGetAuthInfoFunc callback pointer if you want to be able to fetch password-protected web pages. If you don't need to do this, feel free to call this with a NULL pointer.

Use GrabUrl_read() to specify an URL to fetch and an MBuf object in which to place the resulting web page. If you specify a NULL for the MBuf object, a new one will be created for you. The return value is a pointer to the MBuf object.

Use GrabUrl_setAuthInfo() to specify an URL, a realm string (or NULL), plus a base-64-encoded "username:password" string that should be used to access this URL. The supplied data is hashed and stored in an internal array for use by the URL-fetching routines. If URL is the string "proxy" (case ignored), then the authorization information for accessing the proxy server is stored.

GrabUrl_getAuthInfo() is called internally whenever we want to fetch a web page. The result is the headers (if any) that are needed to fetch the indicated URL (if known). The headers include the proxy authorization info.

The GrabUrl_askForAuthInfo() routine takes the provided URL and a nano-http context pointer and checks to see if we already know what password goes with this realm. If not, we call the user-supplied authorization-prompting routine (if available). The returned value is the authorization header information needed for this web page or NULL.

Callbacks

If you supply a GrabUrlAskForAuthInfoFunc pointer to the init routine, your function will receive the URL and the realm when we need to ask the user for a username and a password to access a web page. Your routine should pass these items plus the username/password that the user supplies to the GrabUrl_setAuthInfo() function, and return the string that it returns.