Annotation of libwww/Library/src/HTChannl.html, revision 2.4
2.1 frystyk 1: <HTML>
2: <HEAD>
2.3 eric 3: <TITLE>W3C Reference Library libwww Channel Interface</TITLE>
4: <!-- Changed by: Henrik Frystyk Nielsen, 8-Apr-1996 -->
5: <!-- Changed by: Eric Prud'hommeaux, 27-May-1996 -->
2.4 ! frystyk 6: <!-- Changed by: Henrik Frystyk Nielsen, 2-Jul-1996 -->
2.3 eric 7: <NEXTID N="z18">
2.1 frystyk 8: </HEAD>
9: <BODY>
2.2 frystyk 10: <H1>
11: The Channel Class
12: </H1>
2.1 frystyk 13: <PRE>
14: /*
15: ** (c) COPYRIGHT MIT 1995.
16: ** Please first read the full copyright statement in the file COPYRIGH.
17: */
18: </PRE>
2.2 frystyk 19: <P>
20: A channel contains information about sockets and their input and output streams.
21: A <CODE>channel</CODE> represents the front end for receiving data towards
22: the underlying transport. The definition of a channel describes how we are
23: to read the data coming in on a socket, for example. In other words - a channel
24: represents the first part of how to get handle incoming data in the Library:
25: <P>
2.1 frystyk 26: <UL>
2.2 frystyk 27: <LI>
28: Reading data on a channel
29: <LI>
30: Defining a target for incoming data
31: <LI>
32: Defining a protocol state machine that can handle the data
2.1 frystyk 33: </UL>
2.2 frystyk 34: <P>
35: This module is implemented by <A HREF="HTChannl.c">HTChannl.c</A>, and it
36: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
37: Library</A>.
2.1 frystyk 38: <PRE>
39: #ifndef HTCHANNL_H
40: #define HTCHANNL_H
41:
42: typedef enum _HTChannelMode {
43: HT_CH_SINGLE = 0, /* One single request at a time */
44: HT_CH_BATCH = 1, /* Use batch requests */
45: HT_CH_INTERLEAVED = 2 /* Can we interleave requests? */
46: } HTChannelMode;
47:
48: typedef struct _HTChannel HTChannel;
49:
50: #include <A HREF="HTTrans.html">"HTTrans.h"</A>
51: #include <A HREF="HTReq.html">"HTReq.h"</A>
52: #include <A HREF="HTNet.html">"HTNet.h"</A>
53: #include <A HREF="HTIOStream.html">"HTIOStream.h"</A>
54: </PRE>
2.2 frystyk 55: <H2>
56: The Channel Object
57: </H2>
58: <P>
59: A channel can be in a certain <CODE>mode</CODE> which determines how it behaves.
60: The set of modes is defined as:
61: <H3>
62: Creating a Channel Object
63: </H3>
64: <P>
65: The following methods can be used to instantiate objects of a particular
66: channel mode:
2.1 frystyk 67: <PRE>
68: extern HTChannel * HTChannel_new (HTNet * net, BOOL active);
69: </PRE>
2.2 frystyk 70: <H3>
71: Deleting a Channel Object
72: </H3>
2.1 frystyk 73: <PRE>
2.3 eric 74: extern BOOL HTChannel_delete (HTChannel * channel, int status);
2.1 frystyk 75: extern BOOL HTCannel_deleteAll (void);
76: </PRE>
2.2 frystyk 77: <H3>
78: Control the Channel Mode
79: </H3>
80: <P>
81: A channel may change mode in the middle of a connection. The mode signifies
82: how we can use the channel: Does it accept multiple requets at the same time
83: or do we have to wait until a response is received? Can it handle interleaved
84: (multiplexed) requests/responses etc. All this is defined by the
85: <CODE>HTChannelMode</CODE>. At the same time we return whether the channel
86: is active or passive which means whether we did the initial "connect" or
87: the "accept". The "connect" and the "accept" term is of course a function
88: of the underlying transport but I think you get the point!
2.1 frystyk 89: <PRE>
90: extern HTChannelMode HTChannel_mode (HTChannel * channel, BOOL * active);
91:
92: extern BOOL HTChannel_setMode (HTChannel * channel, HTChannelMode mode);
93: </PRE>
2.2 frystyk 94: <H3>
95: Search for a Channel
96: </H3>
97: <P>
2.1 frystyk 98: Look for a channel object if we for some reason should have lost it
99: <PRE>
100: extern HTChannel * HTChannel_find (SOCKET sockfd);
101: </PRE>
2.2 frystyk 102: <H3>
103: Is the Channel Idle?
104: </H3>
105: <P>
106: Check whether a channel is idle meaning if it is ready for a new request
107: which depends on the mode of the channel. If the channel is idle, i.e. ready
108: for use then return YES else NO.
2.1 frystyk 109: <PRE>
110: extern BOOL HTChannel_idle (HTChannel * channel);
111: </PRE>
2.2 frystyk 112: <H3>
113: Get Transport Descriptor for Channel
114: </H3>
115: <P>
116: A transport descriptor can be either a ANSI C file descriptor or a BSD socket.
117: As it is difficult for the channel to know which one is used by a specific
118: transport, we leave this to the caller to figure out. This is probably not
119: the best way of doing it.
120: <PRE>extern SOCKET HTChannel_socket (HTChannel * channel);
121: extern FILE * HTChannel_file (HTChannel * channel);
122:
123: </PRE>
124: <H3>
125: Semaphores
126: </H3>
127: <P>
128: Adjust the semaphore on a channel. As many <A HREF="HTNet.html">Net objects
129: </A>can point to the same channel we need to keep count of them so that we
130: know if we can delete a channel or if it is still in use. We do this by having
131: a simple semaphore associated with each channel object
2.1 frystyk 132: <PRE>
2.4 ! frystyk 133: extern void HTChannel_upSemaphore (HTChannel * channel);
2.1 frystyk 134: extern void HTChannel_downSemaphore (HTChannel * channel);
2.4 ! frystyk 135: extern void HTChannel_setSemaphore (HTChannel * channel, int semaphore);
2.1 frystyk 136: </PRE>
2.2 frystyk 137: <H3>
138: Create Input and Output Streams
139: </H3>
140: <P>
141: You create the input stream and bind it to the channel using the following
142: methods. Please read the description in the
143: <A HREF="HTIOStream.html">HTIOStream module</A> on the parameters
144: <EM>target</EM>, <EM>param</EM>, and <EM>mode</EM>. The input and output
145: stream are instances created by the <A HREF="HTTrans.html">Transport
146: object</A>. The Transport Object defines the creation methods for the inout
147: and output streams and the Channel object contains the actualy stream objects.
2.1 frystyk 148: <PRE>
149: extern BOOL HTChannel_setInput (HTChannel * ch,
150: HTInputStream * input, HTChannelMode mode);
2.2 frystyk 151: extern HTInputStream * HTChannel_input (HTChannel * ch);
152:
2.1 frystyk 153:
154: extern BOOL HTChannel_setOutput (HTChannel * ch,
155: HTOutputStream * output, HTChannelMode mode);
156: extern HTOutputStream * HTChannel_output (HTChannel * ch);
157:
158: </PRE>
159: <PRE>
160: #endif /* HTCHANNL */
161: </PRE>
2.2 frystyk 162: <P>
163: <HR>
2.1 frystyk 164: <ADDRESS>
2.4 ! frystyk 165: @(#) $Id: HTChannl.html,v 2.3 1996/06/03 19:25:09 eric Exp $
2.1 frystyk 166: </ADDRESS>
2.2 frystyk 167: </BODY></HTML>
Webmaster