The Channel Class

/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/

A channel contains information about sockets and their input and output streams. A channel represents the front end for receiving data towards the underlying transport. The definition of a channel describes how we are to read the data coming in on a socket, for example. In other words - a channel represents the first part of how to get handle incoming data in the Library:

This module is implemented by HTChannl.c, and it is a part of the W3C Reference Library.

#ifndef HTCHANNL_H
#define HTCHANNL_H

typedef enum _HTChannelMode {
    HT_CH_SINGLE	= 0,		/* One single request at a time */
    HT_CH_BATCH		= 1,		/* Use batch requests */
    HT_CH_INTERLEAVED	= 2		/* Can we interleave requests? */
} HTChannelMode;

typedef struct _HTChannel HTChannel;

#include "HTTrans.h"
#include "HTReq.h"
#include "HTNet.h"
#include "HTIOStream.h"

The Channel Object

A channel can be in a certain mode which determines how it behaves. The set of modes is defined as:

Creating a Channel Object

The following methods can be used to instantiate objects of a particular channel mode:

extern HTChannel * HTChannel_new (HTNet * net, BOOL active);

Deleting a Channel Object

extern BOOL HTChannel_delete (HTChannel * channel, int status);
extern BOOL HTCannel_deleteAll (void);

Control the Channel Mode

A channel may change mode in the middle of a connection. The mode signifies how we can use the channel: Does it accept multiple requets at the same time or do we have to wait until a response is received? Can it handle interleaved (multiplexed) requests/responses etc. All this is defined by the HTChannelMode. At the same time we return whether the channel is active or passive which means whether we did the initial "connect" or the "accept". The "connect" and the "accept" term is of course a function of the underlying transport but I think you get the point!

extern HTChannelMode HTChannel_mode (HTChannel * channel, BOOL * active);

extern BOOL HTChannel_setMode (HTChannel * channel, HTChannelMode mode);

Search for a Channel

Look for a channel object if we for some reason should have lost it

extern HTChannel * HTChannel_find (SOCKET sockfd);

Is the Channel Idle?

Check whether a channel is idle meaning if it is ready for a new request which depends on the mode of the channel. If the channel is idle, i.e. ready for use then return YES else NO.

extern BOOL HTChannel_idle (HTChannel * channel);

Get Transport Descriptor for Channel

A transport descriptor can be either a ANSI C file descriptor or a BSD socket. As it is difficult for the channel to know which one is used by a specific transport, we leave this to the caller to figure out. This is probably not the best way of doing it.

extern SOCKET HTChannel_socket	(HTChannel * channel);
extern FILE * HTChannel_file	(HTChannel * channel);

Semaphores

Adjust the semaphore on a channel. As many Net objects can point to the same channel we need to keep count of them so that we know if we can delete a channel or if it is still in use. We do this by having a simple semaphore associated with each channel object

extern void HTChannel_upSemaphore (HTChannel * channel);
extern void HTChannel_downSemaphore (HTChannel * channel);

Create Input and Output Streams

You create the input stream and bind it to the channel using the following methods. Please read the description in the HTIOStream module on the parameters target, param, and mode. The input and output stream are instances created by the Transport object. The Transport Object defines the creation methods for the inout and output streams and the Channel object contains the actualy stream objects.

extern BOOL HTChannel_setInput (HTChannel * ch,
				HTInputStream * input, HTChannelMode mode);
extern HTInputStream * HTChannel_input (HTChannel * ch);


extern BOOL HTChannel_setOutput (HTChannel * ch,
				 HTOutputStream * output, HTChannelMode mode);
extern HTOutputStream * HTChannel_output (HTChannel * ch);

#endif /* HTCHANNL */


@(#) $Id: HTChannl.html,v 2.3 1996/06/03 19:25:09 eric Exp $