Annotation of libwww/Library/src/HTProt.html, revision 2.26
2.25 kahan 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2: "http://www.w3.org/TR/REC-html40/loose.dtd">
3: <html>
4: <head>
5:
6: <!-- Changed by: Henrik Frystyk Nielsen, 26-Mar-1996 -->
7: <NEXTID N="z11"><title>W3C Sample Code Library libwww Protocol Class</title>
8: </head>
9: <body>
10:
11: <h1>The Protocol Class</h1>
12: <pre>/*
13: ** (c) COPYRIGHT MIT 1995.
14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */</pre>
16:
17: <p>The Protocol class defines an application level protocol (HTTP, FTP,
18: Gopher, etc.) to be used by libwww. Note that access to the local file system
19: also is considered to be an appliaction level protocol treated identically to
20: for example the HTTP protocol.</p>
21:
22: <p>The Protocol class does only know about the application layer protocol and
23: it relies on the <a href="HTTrans.html">Transport Class</a> to do the actualt
24: communication with the network, the local file system etc. The protocol class
25: defines an access method for both a client and a server. A typical client
26: application would probably only want to use the client method and a server
27: only the server method. However, any application can use both which allows it
28: to seemlessly to change between server and client profile as needed.</p>
29:
30: <p>All protocol modules are dynamically bound to an access scheme. Take for
31: example the address <code>http://www.w3.org</code> which has the access scheme
32: <b>http</b> and if we have a protocol module capable of handling HTTP then we
33: can make the binding between <b>http</b> and this module. As mentioned in the
34: introduction to this chapter, the Library already comes with a large set of
35: protocol module, including HTTP so all we have to do in this case is to
36: register the HTTP module to the Library as being capable of handling
37: <b>http</b> URLs.</p>
38:
39: <p>Libwww comes with a default set of protocols including the ones mentioned
40: above which can be initiated using the function <code>HTProtocolInit()</code>
41: in <a href="HTInit.html">HTInit module</a></p>
42:
43: <p>One special case is the support for access to WAIS
44: databases. WAIS has its own code Library
45: called <a href="http://www.cnidr.org/">freeWAIS</a> which is required in order
46: to directly access wais URLs. We shall not describe in describe in detail here
47: how this can be enabled as it is described in the <a
48: href="/Gateways/WAISGate.html">WWW-WAIS gateway</a>.</p>
49:
50: <p>This module is implemented by <a href="HTProt.c">HTProt.c</a>, and it is a
51: part of the <a href="http://www.w3.org/Library/"> W3C Sample Code
52: Library</a>.</p>
2.26 ! vbancrof 53: <pre>
! 54: #ifndef HTPROT_H
2.1 frystyk 55: #define HTPROT_H
56:
2.26 ! vbancrof 57: #ifdef __cplusplus
! 58: extern "C" {
! 59: #endif
! 60:
2.21 frystyk 61: typedef struct _HTProtocol HTProtocol;
62: typedef u_short HTProtocolId;
63:
2.5 frystyk 64: #include "HTReq.h"
2.1 frystyk 65: #include "HTAnchor.h"
2.16 eric 66: #include "HTEvent.h"
2.25 kahan 67: #include "HTTrans.h"</pre>
68:
69: <p>An access scheme module takes as a parameter a socket (which is an invalid
70: socket the first time the function is called), a <a
71: href="HTReqMan.html">request structure</a> containing details of the request,
2.16 eric 72: and the action by which the (valid) socket was selected in the event loop.
73: When the protocol class routine is called, the anchor element in the request
2.25 kahan 74: is already valid (made valid by HTAccess).</p>
75:
76: <h2>Creation and Deletion Methods</h2>
77:
78: <h3>Add an Protocol</h3>
79:
80: <p>This functions registers a protocol module and binds it to a specific
81: access acheme (the part before the first colon in a URL). For example, the
82: HTTP client module is bound to http URLs. The callback function is the
83: function to be called for loading.</p>
84: <pre>typedef int HTProtCallback (SOCKET, HTRequest *);
85:
86: extern BOOL HTProtocol_add (const char * name,
87: const char * transport,
88: HTProtocolId port,
89: BOOL preemptive,
90: HTProtCallback * client,
91: HTProtCallback * server);</pre>
92:
93: <h3>Delete a Protocol</h3>
94:
95: <p>This functions deletes a registered protocol module so that it can not be
96: used for accessing a resource anymore.</p>
97: <pre>extern BOOL HTProtocol_delete (const char * name);</pre>
98:
99: <h3>Remove ALL Registered Protocols</h3>
100:
101: <p>This is the garbage collection function. It is called by <a
102: href="HTLib.html">HTLibTerminate()</a></p>
103: <pre>extern BOOL HTProtocol_deleteAll (void);</pre>
104:
105: <h2>Protocol Class Methods</h2>
106:
107: <h3>Find a Protocol Object</h3>
108:
109: <p>You can search the list of registered protocol objects as a function of the
110: access acheme. If an access scheme is found then the protocol object is
111: returned.</p>
112: <pre>extern HTProtocol * HTProtocol_find (HTRequest * request, const char * access);</pre>
113:
114: <h3>Get the callback functions</h3>
115:
116: <p>You can get the callback functions registered together with a protocol
117: object using the following methods.</p>
118: <pre>extern HTProtCallback * HTProtocol_client (HTProtocol * protocol);
119: extern HTProtCallback * HTProtocol_server (HTProtocol * protocol);</pre>
120:
121: <h3>Get the default Protocol ID</h3>
122:
123: <p>Each protocol is registered with a default protocol ID which is the default
124: port number that this protocol is using. In the case of FTP it is 21, for
125: HTTP, it is 80 and for NNTP it is 119.</p>
126: <pre>extern HTProtocolId HTProtocol_id (HTProtocol * protocol);</pre>
127:
128: <h3>Get the Protocol Name</h3>
129:
130: <p>Get the protocol name that was registered when the protocol object was
131: created</p>
132: <pre>extern const char * HTProtocol_name (HTProtocol * protocol);</pre>
133:
134: <h3>Is Access Scheme Preemptive</h3>
135:
136: <p>Returns YES if the implementation of the access scheme supports preemptive
137: access only.</p>
138: <pre>extern BOOL HTProtocol_preemptive (HTProtocol * protocol);</pre>
139:
140: <h3>Binding to the Transport Class</h3>
141:
142: <p>An application protocol is registered together with a <a
143: href="HTTrans.html">transport protocol </a>in order to communicate with the
144: thansport layer.</p>
145: <pre>extern BOOL HTProtocol_setTransport (HTProtocol * protoccol,
146: const char * transport);
147: extern const char * HTProtocol_transport (HTProtocol * protocol);</pre>
2.26 ! vbancrof 148: <pre>
! 149: #ifdef __cplusplus
! 150: }
! 151: #endif
! 152:
! 153: #endif /* HTPROT_H */
! 154: </pre>
2.25 kahan 155:
156: <hr>
157:
158: <address>
2.26 ! vbancrof 159: @(#) $Id: HTProt.html,v 2.25 1999/12/01 13:07:07 kahan Exp $ </address>
2.25 kahan 160: </body>
161: </html>
Webmaster