Annotation of libwww/Library/src/HTCookie.html, revision 2.3
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>W3C Sample Code Library libwww Simple Cookie Handler</TITLE>
4: </HEAD>
5: <BODY>
6: <H1>
7: Simple Cookie Handler
8: </H1>
9: <PRE>
10: /*
11: ** (c) COPYRIGHT MIT 1999.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
15: <P>
16: This module provides a simple
17: <A HREF="http://www.netscape.com/newsref/std/cookie_spec.html">HTTP Cookie
18: handling mechanism</A>. It really also is an excersize in showing how libwww
19: can be extended with something like cookies in a modular manner. An important
20: thing to note about this implementation is that it does <EM>not</EM> provide
21: storage for cookies - this is left to the application as normally cookies
22: have to be kept under lock.
23: <P>
24: This module is implemented by <A HREF="HTCookie.c">HTCookie.c</A>, and it
25: is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
26: Library</A>.
27: <PRE>
28: #ifndef HTCOOKIE_H
29: #define HTCOOKIE_H
30: #include "WWWLib.h"
31: </PRE>
32: <H2>
33: <A NAME="Init">Initiate and Terminate Cookie Handling</A>
34: </H2>
35: <P>
36: In order to start handling cookies, you need to initiate the module. Likewise,
37: when you are done, you must terminate the module in order to clean up memory
38: etc. Note that this cookie handler doesn't provide storage room for cookies
39: - the application MUST do that by <A HREF="#Callbacks">registering cookie
40: callbacks</A>. Initiation does three things:
41: <OL>
42: <LI>
43: Register a <A HREF="HTHeader.html">MIME header parser</A> to parse the Set-Cookie
44: header field
45: <LI>
46: Register a <A HREF="HTNet.html">BEFORE filter</A> to see if a cookie should
47: be added to the request (uses the <A HREF="#Callbacks">"set" callback</A>)
48: <LI>
49: Register an <A HREF="HTNet.html">AFTER filter</A> to handle new cookies (uses
50: the <A HREF="#Callbacks">"find" callback</A>)
51: </OL>
52: <PRE>
53: extern BOOL HTCookie_init (void);
54: extern BOOL HTCookie_terminate (void);
55: </PRE>
56: <H2>
57: <A NAME="Cookie">The Cookie Class</A>
58: </H2>
59: <P>
60: The cookie class is used to handle cookies in libwww and to hand them off
61: to the application. The creation and deletion of cookie object is handled
62: by this cookie module - the application is handed a cookie and can access
63: the elements using the following methods:
64: <PRE>
65: typedef struct _HTCookie HTCookie;
66: </PRE>
67: <H3>
68: Cookie Name
69: </H3>
70: <PRE>
71: extern BOOL HTCookie_setName (HTCookie * me, const char * name);
72: extern char * HTCookie_name (HTCookie * me);
73: </PRE>
74: <H3>
75: Cookie Value
76: </H3>
77: <PRE>
78: extern BOOL HTCookie_setValue (HTCookie * me, const char * value);
79: extern char * HTCookie_value (HTCookie * me);
80: </PRE>
81: <H3>
82: Cookie Domain
83: </H3>
84: <PRE>
85: extern BOOL HTCookie_setDomain (HTCookie * me, const char * domain);
86: extern char * HTCookie_domain (HTCookie * me);
87: </PRE>
88: <H3>
89: Cookie Path
90: </H3>
91: <PRE>
92: extern BOOL HTCookie_setPath (HTCookie * me, const char * path);
93: extern char * HTCookie_path (HTCookie * me);
94: </PRE>
95: <H3>
96: Cookie Expiration
97: </H3>
98: <PRE>
99: extern time_t HTCookie_setExpiration (HTCookie * me, time_t expiration);
100: extern time_t HTCookie_expiration (HTCookie * me);
101: </PRE>
102: <H3>
103: Is Cookie Secure?
104: </H3>
105: <PRE>
106: extern time_t HTCookie_setSecure (HTCookie * me, BOOL secure);
107: extern BOOL HTCookie_isSecure (HTCookie * me);
108: </PRE>
109: <H2>
110: <A NAME="Callbacks">Cookie Callbacks</A>
111: </H2>
112: <P>
113: The cookie callbacks are called before the request is shipped over the wire
114: to see if any cookies should be included and after the response has been
115: recieved if a new cookie is found in a response and before. Cookie callbacks
116: can be registered with a context that is sent along with the callback when
117: called.
118: <PRE>
119: typedef BOOL HTCookieSetCallback (HTRequest * request, HTCookie * cookie, void * param);
120: typedef HTAssocList * HTCookieFindCallback (HTRequest * request, void * param);
121:
122: extern BOOL HTCookie_setCallbacks (HTCookieSetCallback * setCookie,
123: void * setCookieContext,
124: HTCookieFindCallback * findCookie,
125: void * findCookieContext);
126: extern BOOL HTCookie_deleteCallbacks (void);
127: </PRE>
128: <H2>
129: <A NAME="Mode">Cookie Handling Mode</A>
130: </H2>
131: <P>
132: The application can decide how cookies are to be handled - should they be
133: ignored, should the user be asked, etc.
134: <PRE>
135: typedef enum _HTCookieMode {
2.3 ! raff 136: HT_COOKIE_ACCEPT = 0x1, /* Accept cookies */
! 137: HT_COOKIE_SEND = 0x2, /* Send cookies when fit */
! 138: HT_COOKIE_SAME_HOST = 0x4, /* Don't accept cookies for other hosts */
! 139: HT_COOKIE_SAME_DOMAIN = 0x8, /* Don't accept cookies for other domains */
! 140: HT_COOKIE_PROMPT = 0x10 /* Prompt before accepting cookies */
2.1 frystyk 141: } HTCookieMode;
142:
143: extern BOOL HTCookie_setCookieMode (HTCookieMode mode);
2.2 frystyk 144: extern HTCookieMode HTCookie_cookieMode (void);
2.1 frystyk 145: </PRE>
146: <PRE>
147: #endif /* HTCOOKIE_H */
148: </PRE>
149: <P>
150: <HR>
151: <ADDRESS>
2.3 ! raff 152: @(#) $Id: HTCookie.html,v 2.2 1999/04/01 19:36:32 frystyk Exp $
2.1 frystyk 153: </ADDRESS>
154: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTCookie.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src