Annotation of libwww/Library/src/HTProt.html, revision 2.25
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>
! 53: <pre>#ifndef HTPROT_H
2.1 frystyk 54: #define HTPROT_H
55:
2.21 frystyk 56: typedef struct _HTProtocol HTProtocol;
57: typedef u_short HTProtocolId;
58:
2.5 frystyk 59: #include "HTReq.h"
2.1 frystyk 60: #include "HTAnchor.h"
2.16 eric 61: #include "HTEvent.h"
2.25 ! kahan 62: #include "HTTrans.h"</pre>
! 63:
! 64: <p>An access scheme module takes as a parameter a socket (which is an invalid
! 65: socket the first time the function is called), a <a
! 66: href="HTReqMan.html">request structure</a> containing details of the request,
2.16 eric 67: and the action by which the (valid) socket was selected in the event loop.
68: When the protocol class routine is called, the anchor element in the request
2.25 ! kahan 69: is already valid (made valid by HTAccess).</p>
! 70:
! 71: <h2>Creation and Deletion Methods</h2>
! 72:
! 73: <h3>Add an Protocol</h3>
! 74:
! 75: <p>This functions registers a protocol module and binds it to a specific
! 76: access acheme (the part before the first colon in a URL). For example, the
! 77: HTTP client module is bound to http URLs. The callback function is the
! 78: function to be called for loading.</p>
! 79: <pre>typedef int HTProtCallback (SOCKET, HTRequest *);
! 80:
! 81: extern BOOL HTProtocol_add (const char * name,
! 82: const char * transport,
! 83: HTProtocolId port,
! 84: BOOL preemptive,
! 85: HTProtCallback * client,
! 86: HTProtCallback * server);</pre>
! 87:
! 88: <h3>Delete a Protocol</h3>
! 89:
! 90: <p>This functions deletes a registered protocol module so that it can not be
! 91: used for accessing a resource anymore.</p>
! 92: <pre>extern BOOL HTProtocol_delete (const char * name);</pre>
! 93:
! 94: <h3>Remove ALL Registered Protocols</h3>
! 95:
! 96: <p>This is the garbage collection function. It is called by <a
! 97: href="HTLib.html">HTLibTerminate()</a></p>
! 98: <pre>extern BOOL HTProtocol_deleteAll (void);</pre>
! 99:
! 100: <h2>Protocol Class Methods</h2>
! 101:
! 102: <h3>Find a Protocol Object</h3>
! 103:
! 104: <p>You can search the list of registered protocol objects as a function of the
! 105: access acheme. If an access scheme is found then the protocol object is
! 106: returned.</p>
! 107: <pre>extern HTProtocol * HTProtocol_find (HTRequest * request, const char * access);</pre>
! 108:
! 109: <h3>Get the callback functions</h3>
! 110:
! 111: <p>You can get the callback functions registered together with a protocol
! 112: object using the following methods.</p>
! 113: <pre>extern HTProtCallback * HTProtocol_client (HTProtocol * protocol);
! 114: extern HTProtCallback * HTProtocol_server (HTProtocol * protocol);</pre>
! 115:
! 116: <h3>Get the default Protocol ID</h3>
! 117:
! 118: <p>Each protocol is registered with a default protocol ID which is the default
! 119: port number that this protocol is using. In the case of FTP it is 21, for
! 120: HTTP, it is 80 and for NNTP it is 119.</p>
! 121: <pre>extern HTProtocolId HTProtocol_id (HTProtocol * protocol);</pre>
! 122:
! 123: <h3>Get the Protocol Name</h3>
! 124:
! 125: <p>Get the protocol name that was registered when the protocol object was
! 126: created</p>
! 127: <pre>extern const char * HTProtocol_name (HTProtocol * protocol);</pre>
! 128:
! 129: <h3>Is Access Scheme Preemptive</h3>
! 130:
! 131: <p>Returns YES if the implementation of the access scheme supports preemptive
! 132: access only.</p>
! 133: <pre>extern BOOL HTProtocol_preemptive (HTProtocol * protocol);</pre>
! 134:
! 135: <h3>Binding to the Transport Class</h3>
! 136:
! 137: <p>An application protocol is registered together with a <a
! 138: href="HTTrans.html">transport protocol </a>in order to communicate with the
! 139: thansport layer.</p>
! 140: <pre>extern BOOL HTProtocol_setTransport (HTProtocol * protoccol,
! 141: const char * transport);
! 142: extern const char * HTProtocol_transport (HTProtocol * protocol);</pre>
! 143: <pre>#endif /* HTPROT_H */</pre>
! 144:
! 145: <p></p>
! 146: <hr>
! 147:
! 148: <address>
! 149: @(#) $Id: HTProt.html,v 2.24 1998/12/15 05:34:28 frystyk Exp $ </address>
! 150: </body>
! 151: </html>
Webmaster