Annotation of libwww/Library/src/HTCookie.html, revision 2.4
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"
2.4 ! vbancrof 31:
! 32: #ifdef __cplusplus
! 33: extern "C" {
! 34: #endif
2.1 frystyk 35: </PRE>
36: <H2>
37: <A NAME="Init">Initiate and Terminate Cookie Handling</A>
38: </H2>
39: <P>
40: In order to start handling cookies, you need to initiate the module. Likewise,
41: when you are done, you must terminate the module in order to clean up memory
42: etc. Note that this cookie handler doesn't provide storage room for cookies
43: - the application MUST do that by <A HREF="#Callbacks">registering cookie
44: callbacks</A>. Initiation does three things:
45: <OL>
46: <LI>
47: Register a <A HREF="HTHeader.html">MIME header parser</A> to parse the Set-Cookie
48: header field
49: <LI>
50: Register a <A HREF="HTNet.html">BEFORE filter</A> to see if a cookie should
51: be added to the request (uses the <A HREF="#Callbacks">"set" callback</A>)
52: <LI>
53: Register an <A HREF="HTNet.html">AFTER filter</A> to handle new cookies (uses
54: the <A HREF="#Callbacks">"find" callback</A>)
55: </OL>
56: <PRE>
57: extern BOOL HTCookie_init (void);
58: extern BOOL HTCookie_terminate (void);
59: </PRE>
60: <H2>
61: <A NAME="Cookie">The Cookie Class</A>
62: </H2>
63: <P>
64: The cookie class is used to handle cookies in libwww and to hand them off
65: to the application. The creation and deletion of cookie object is handled
66: by this cookie module - the application is handed a cookie and can access
67: the elements using the following methods:
68: <PRE>
69: typedef struct _HTCookie HTCookie;
70: </PRE>
71: <H3>
72: Cookie Name
73: </H3>
74: <PRE>
75: extern BOOL HTCookie_setName (HTCookie * me, const char * name);
76: extern char * HTCookie_name (HTCookie * me);
77: </PRE>
78: <H3>
79: Cookie Value
80: </H3>
81: <PRE>
82: extern BOOL HTCookie_setValue (HTCookie * me, const char * value);
83: extern char * HTCookie_value (HTCookie * me);
84: </PRE>
85: <H3>
86: Cookie Domain
87: </H3>
88: <PRE>
89: extern BOOL HTCookie_setDomain (HTCookie * me, const char * domain);
90: extern char * HTCookie_domain (HTCookie * me);
91: </PRE>
92: <H3>
93: Cookie Path
94: </H3>
95: <PRE>
96: extern BOOL HTCookie_setPath (HTCookie * me, const char * path);
97: extern char * HTCookie_path (HTCookie * me);
98: </PRE>
99: <H3>
100: Cookie Expiration
101: </H3>
102: <PRE>
103: extern time_t HTCookie_setExpiration (HTCookie * me, time_t expiration);
104: extern time_t HTCookie_expiration (HTCookie * me);
105: </PRE>
106: <H3>
107: Is Cookie Secure?
108: </H3>
109: <PRE>
110: extern time_t HTCookie_setSecure (HTCookie * me, BOOL secure);
111: extern BOOL HTCookie_isSecure (HTCookie * me);
112: </PRE>
113: <H2>
114: <A NAME="Callbacks">Cookie Callbacks</A>
115: </H2>
116: <P>
117: The cookie callbacks are called before the request is shipped over the wire
118: to see if any cookies should be included and after the response has been
119: recieved if a new cookie is found in a response and before. Cookie callbacks
120: can be registered with a context that is sent along with the callback when
121: called.
122: <PRE>
123: typedef BOOL HTCookieSetCallback (HTRequest * request, HTCookie * cookie, void * param);
124: typedef HTAssocList * HTCookieFindCallback (HTRequest * request, void * param);
125:
126: extern BOOL HTCookie_setCallbacks (HTCookieSetCallback * setCookie,
127: void * setCookieContext,
128: HTCookieFindCallback * findCookie,
129: void * findCookieContext);
130: extern BOOL HTCookie_deleteCallbacks (void);
131: </PRE>
132: <H2>
133: <A NAME="Mode">Cookie Handling Mode</A>
134: </H2>
135: <P>
136: The application can decide how cookies are to be handled - should they be
137: ignored, should the user be asked, etc.
138: <PRE>
139: typedef enum _HTCookieMode {
2.3 raff 140: HT_COOKIE_ACCEPT = 0x1, /* Accept cookies */
141: HT_COOKIE_SEND = 0x2, /* Send cookies when fit */
142: HT_COOKIE_SAME_HOST = 0x4, /* Don't accept cookies for other hosts */
143: HT_COOKIE_SAME_DOMAIN = 0x8, /* Don't accept cookies for other domains */
144: HT_COOKIE_PROMPT = 0x10 /* Prompt before accepting cookies */
2.1 frystyk 145: } HTCookieMode;
146:
147: extern BOOL HTCookie_setCookieMode (HTCookieMode mode);
2.2 frystyk 148: extern HTCookieMode HTCookie_cookieMode (void);
2.1 frystyk 149: </PRE>
150: <PRE>
2.4 ! vbancrof 151: #ifdef __cplusplus
! 152: }
! 153: #endif
! 154:
2.1 frystyk 155: #endif /* HTCOOKIE_H */
156: </PRE>
157: <P>
158: <HR>
159: <ADDRESS>
2.4 ! vbancrof 160: @(#) $Id: HTCookie.html,v 2.3 1999/07/31 01:30:16 raff Exp $
2.1 frystyk 161: </ADDRESS>
162: </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