Re: Cache/proxy documentation

Philippe Martin wrote:
> 
> I found the use of caches and proxies in the library poorly documented on some
> aspects.

I agree that the documentation is not always the best but this is why I
ask you to help fixing it - in fact it is often much more useful to have
you do it instead of me as I know what is going on already.

> My first problem was to declare a proxy and have a user identifier and
> password automatically sent to the proxy instead of being asked to the user
> at each request. After browsing the code and the documentation about caches
> and proxies, the only solution I found was to directly call the function
> HTAA_updateNode() from my program, and to do that I had to duplicate the
> structure HTBasic.
>     typedef struct { char *uid; char *pw; BOOL retry; BOOL proxy; } myHTBasic;
>     myHTBasic *basic = (myHTBasic *) calloc(1, sizeof(myHTBasic));
>     basic->uid  = strdup(PROXY_UID);
>     basic->pw = my_strdup(PROXY_PASSWD);
>     basic->retry= NO;  basic->proxy = YES;
>     HTAA_updateNode(YES,"basic",PROXY_REALM,HTTP_PROXY,basic);
> The documentation didn't help me to find this solution.

No need to copy code. You can see an example of "automatic" password
authentication for end-to-end authentication in the command line tool.
This is described at

	http://www.w3.org/ComLine/User/CommandLine.html#auth

The way this works in libwww is that you can register an alert handler
for handling interactions with the user. In the case of proxy auth you
have to register an alert handler for op code HT_A_USER_PW. You can see
how this is done in 

	http://www.w3.org/ComLine/src/HTLine.c

where you can find this code

    /*
    ** Delete the default Username/password handler so that we can
handle
    ** parameters handed to us from the command line. The default is set
    ** by the profile.
    */
    HTAlert_deleteOpcode(HT_A_USER_PW);
    HTAlert_add(PromptUsernameAndPassword, HT_A_USER_PW);	

When handling proxy authentication, the HT_A_USER_PW handler is called
with msg number HT_MSG_PROXY_UID, if normal auth the msg number is
HT_MSG_UID. That way, you can auto fill-in the credentials when
prompted.

The same thing goes for the HT_A_CONFIRM alert handler which is called
in case the crendentials weren't accepted and you have to decide whether
you want to retry or not.
 
> My second problem was that files given back by the proxy were sometimes not
> the latest files. The documentation on proxies or cache management did not
> lead me to a solution. Only recently a network specialist found one for me:
>     HTRequest_addGnHd(W3C_Request,HT_G_PRAGMA_NO_CACHE);
> This command and pragma is refered in HTReq.html#gnhd (section
> "HTTP Header Mask"). The use of the pragma is not explained so I could
> not retrieve it with a "grep cache *.html" or "grep proxy *.html".
> There is also no reference to it in other sections.

Pragma is a HTTP/1.x construct that is deprecated in favor of the more
flexible cache control directive. You can control this directive using
these methods of the HTRequest object:

	http://www.w3.org/Library/src/HTReq.html#Cache

Normally, you want to let the cache do its work - it you want to
refresh/verify the contents in the proxy cache then you should use the
HT_CACHE_VALIDATE mode.

Note that you can also use the rules file to set proxies - you don't
have to hardcode them or to use env variables:

	http://www.w3.org/Library/User/Using/RuleSyntax.html

linked from

	http://www.w3.org/Library/User/Using/  

You can see how the command line tool uses rule files

	http://www.w3.org/ComLine/User/CommandLine.html#Configurat

> The libwww is flexible but complex. I think that the following program
> would be helpful if given in the list of examples. It's called wwwcp.
> It copy a WWW-accessible file (parameter 1) into a local file (parameter 2).
> I do not know if the solution I give is optimal or fully correct (it just
> work correctly when I use it). Please tell me if it is not.

I think it comes pretty close to some of the examples in

	http://www.w3.org/Library/Examples/#GET

But I'll stick it in so that others can see it as well.

--
Henrik Frystyk Nielsen,
World Wide Web Consortium
http://www.w3.org/People/Frystyk

Received on Tuesday, 23 March 1999 09:54:17 UTC