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